Manual de PHP

por:
MehdiAchour
FriedhelmBetz
AntonyDovgal
NunoLopes
HannesMagnusson
GeorgRichter
DamienSeguy
JakubVrana
2023-06-19
Editado por:PeterCowburn
por:
¿Quieres ayudarnos a traducir?Ponte en contacto con: seros[arroba]php.net
Traduciendo desde Dic-2009. Estado: 80%completo y al día.
Lista de encargados del mantenimiento ytraducción por número de ficheros:
1. Pedro AntonioGil Rodríguez 2. Andrés García 3. Yago Ferrer 4. Jesús Ruiz-Ayúcar Vázquez 5. Juan Pablo Berdejo 6. Alexander Garzon 7. Jesús Ruiz García 8. Marta Regina Cano Jiménez 9. Leonardo Boshell 10. Francisco José Naranjo Abad 11. Jesús Rafael Cova Huerta 12. Jorge Eduardo Olaya P. 13. Edwin Cartagena Hdez. 14. Jesús Díez 15. Diego Agulló Falcó 16. Ernesto Mediavilla del Río 17. Carlos Hernández Afan de Ribera 18. Waldo Malqui Silva 19. Braian Iván Monnier 20. José Mercedes Venegas Acevedo
ymuchos más...

Copyright

Copyright © 1997 - 2023 por el PHP Documentation Group. Este material puede ser distribuido solamente sujeto a los términos y condiciones establecidos por la licencia de Creative Commons Attribution 3.0 o superior. Una copia de laLicencia de Commons Attribution 3.0está distribuida con este manual. La versión más reciente está disponible en» http://creativecommons.org/licenses/by/3.0/.

Si está interesado en la redistribución o republicación de este documento completa o parcialmente, con o sin modificaciones, y si tiene alguna pregunta, por favor contacte con los propietarios del Copyright en» doc-license@lists.php.net. Observe que esta dirección está ligada a una lista de correo pública.



Manual de PHP


Prefacio

PHP, acrónimo de "PHP: Hypertext Preprocessor", es un lenguaje de 'scripting' de propósito general y de código abierto que está especialmente pensado para el desarrollo web y que puede ser embebido en páginas HTML. Su sintaxis recurre a C, Java y Perl, siendo así sencillo de aprender. El objetivo principal de este lenguaje es permitir a los desarrolladores web escribir dinámica y rápidamente páginas web generadas; aunque se puede hacer mucho más con PHP.

Este manual consiste principalmente en unareferencia de funciones, aunque también contiene unareferencia del lenguaje, explicaciones de algunas de lascaracterísticasimportantes de PHP, y otra informaciónsuplementaria.

Este manual se puede descargar en diferentes formatos en» https://www.php.net/download-docs.php. Puede encontrarse más información sobre cómo se desarrolla este manual en el apéndice"Acerca de este manual". Si está interesado en laHistoria de PHP, visite el apéndice correspondiente.

Autores y Contribuyentes

Destacamos a las personas actualmente más activas al frente del manual, pero hay muchos más contribuyentes que nos ayudan en nuestro trabajo o han brindado una gran cantidad de ayuda al proyecto en el pasado. Hay muchísima gente anónima que ayudó con notas de usuario en las páginas del manual, que continuamente son incluidas en las referencias, labor de la que también estamos muy agradecidos. Todas las listas siguientes están en orden alfabético.

Autores y Editores

Los siguientes contribuyentes deberían ser reconocidos por el impacto de lo que han hecho y/o continúan haciendo añadiendo contenido al manual: Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Philip Olson, Richard Quadling, Derick Rethans, Rob Richards, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar y Andrei Zmievski.

Los siguientes contribuyentes han hecho un importante trabajo editando el manual: Stig Bakken, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson y Egon Schmid.

Mantenedores de las Notas de Usuario

Los mantenedores actualmente más activos son: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda y Maciek Sokolewicz.

Estas personas también pusieron mucho esfuerzo en la administración de las notas de usuario: Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles y Jeroen van Wolffelaar.




Conceptos básicos


Introducción

Tabla de contenidos


¿Qué es PHP?

PHP(acrónimo recursivo dePHP: Hypertext Preprocessor) es un lenguaje de código abierto muy popular especialmente adecuado para el desarrollo web y que puede ser incrustado en HTML.

Bien, pero ¿qué significa realmente? Un ejemplo nos aclarará las cosas:

Ejemplo #1 Un ejemplo introductorio

<!DOCTYPE html>
<html>
<head>
<title>Ejemplo</title>
</head>
<body>

<?php
echo"¡Hola, soy un script de PHP!";
?>

</body>
</html>

En lugar de usar muchos comandos para mostrar HTML (como en C o en Perl), las páginas de PHP contienen HTML con código incrustado que hace "algo" (en este caso, mostrar "¡Hola, soy un script de PHP!). El código de PHP está encerrado entre lasetiquetas especiales de comienzo y final<?phpy?>que permiten entrar y salir del "modo PHP".

Lo que distingue a PHP de algo del lado del cliente como Javascript es que el código es ejecutado en el servidor, generando HTML y enviándolo al cliente. El cliente recibirá el resultado de ejecutar el script, aunque no se sabrá el código subyacente que era. El servidor web puede ser configurado incluso para que procese todos los ficheros HTML con PHP, por lo que no hay manera de que los usuarios puedan saber qué se tiene debajo de la manga.

Lo mejor de utilizar PHP es su extrema simplicidad para el principiante, pero a su vez ofrece muchas características avanzadas para los programadores profesionales. No sienta miedo de leer la larga lista de características de PHP. En unas pocas horas podrá empezar a escribir sus primeros scripts.

Aunque el desarrollo de PHP está centrado en la programación de scripts del lado del servidor, se puede utilizar para muchas otras cosas. Siga leyendo y descubra más en la sección¿Qué puede hacer PHP?, o vaya directo altutorial introductoriosi solamente está interesado en programación web.



¿Qué puede hacer PHP?

Cualquier cosa. PHP está enfocado principalmente a la programación de scripts del lado del servidor, por lo que se puede hacer cualquier cosa que pueda hacer otro programa CGI, como recopilar datos de formularios, generar páginas con contenidos dinámicos, o enviar y recibir cookies. Aunque PHP puede hacer mucho más.

Existen principalmente tres campos principales donde se usan scripts de PHP.

  • Scripts del lado del servidor. Este es el campo más tradicional y el foco principal. Son necesarias tres cosas para que esto funcione: el analizador de PHP (módulo CGI o servidor), un servidor web y un navegador web. Es necesario ejecutar el servidor con una instalación de PHP conectada. Se puede acceder al resultado del programa de PHP con un navegador, viendo la página de PHP a través del servidor. Todo esto se puede ejecutar en su máquina si está experimentado con la programación de PHP. Véase la sección sobre lasinstrucciones de instalaciónpara más información.
  • Scripts desde la línea de comandos. Se puede crear un script de PHP y ejecutarlo sin necesidad de un servidor o navegador. Solamente es necesario el analizador de PHP para utilizarlo de esta manera. Este tipo de uso es ideal para scripts que se ejecuten con regularidad empleando cron (en *nix o Linux) o el Planificador de tareas (en Windows). Estos scripts también pueden usarse para tareas simples de procesamiento de texto. Véase la secciónUso de PHP en la línea de comandospara más información.
  • Escribir aplicaciones de escritorio. Probablemente PHP no sea el lenguaje más apropiado para crear aplicaciones de escritorio con una interfaz gráfica de usuario, pero si se conoce bien PHP, y se quisiera utilizar algunas características avanzadas de PHP en aplicaciones del lado del cliente, se puede utilizar PHP-GTK para escribir dichos programas. También es posible de esta manera escribir aplicaciones independientes de una plataforma. PHP-GTK es una extensión de PHP, no disponible en la distribución principal. Si está interesado en PHP-GTK, puede visitar su propio»  sitio web.

PHP puedeemplearseen todos los sistemas operativos principales, incluyendo Linux, muchas variantes de Unix (incluyendo HP-UX, Solaris y OpenBSD), Microsoft Windows, macOS, RISC OS y probablemente otros más. PHP admite la mayoría de servidores web de hoy en día, incluyendo Apache, IIS, y muchos otros. Esto incluye cualquier servidor web que pueda utilizar el binario de PHP FastCGI, como lighttpd y nginx. PHP funciona tanto como módulo como procesador de CGI.

De modo que con PHP, se tiene la libertad de elegir el sistema operativo y el servidor web. Además, se tiene la posibilidad de utilizar programación por procedimientos o programación orientada a objetos (POO), o una mezcla de ambas.

Con PHP no se está limitado a generar HTML. Entre las capacidades de PHP se incluyen la creación de imágenes, ficheros PDF e incluso películas Flash (usando libswf y Ming) generadas sobre la marcha. También se puede generar fácilmente cualquier tipo de texto, como XHTML y cualquier otro tipo de fichero XML. PHP puede autogenerar estos ficheros y guardarlos en el sistema de ficheros en vez de imprimirlos en pantalla, creando una caché en el lado del servidor para contenido dinámico.

Una de las características más potentes y destacables de PHP es su soporte para unamplio abanico de bases de datos. Escribir una página web con acceso a una base de datos es increíblemente simple utilizando una de las extensiones específicas de bases de datos (p.ej., paramysql), o utilizar una capa de abstracción comoPDO, o conectarse a cualquier base de datos que admita el estándar de Conexión Abierta a Bases de Datos por medio de la extensiónODBC. Otras bases de datos podrían utilizarcURLosockets, como lo hace CouchDB.

PHP también cuenta con soporte para comunicarse con otros servicios usando protocolos tales como LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (en Windows) y muchos otros. También se pueden crear sockets de red puros e interactuar usando cualquier otro protocolo. PHP tiene soporte para el intercambio de datos complejos de WDDX entre virtualmente todos los lenguajes de programación web. Y hablando de interconexión, PHP tiene soporte para la instalación de objetos de Java y emplearlos de forma transparente como objetos de PHP.

PHP tiene útiles características deprocesamiento de texto, las cuales incluyen las expresiones regulares compatibles con Perl (PCRE), y muchas extensiones y herramientas para elacceso y análisis de documentos XML. PHP estandariza todas las extensiones XML sobre el fundamento sólido delibxml2, y amplía este conjunto de características añadiendo soporte paraSimpleXML,XMLReaderyXMLWriter.

Existen otras extensiones interesantes, las cuales están categorizadasalfabéticamentey porcategoría. También hay extensiones adicionales de PECL que podrían estar documentadas o no dentro del manual de PHP, tal como» XDebug.

Como se puede apreciar, esta página no es suficiente para enumerar todas las características y beneficios que ofrece PHP. Consulte las seccionesInstalación de PHPyReferencia de las funcionespara una explicación de las extensiones mencionadas aquí.




A continuación, nos gustaría mostrarle lo esencial de PHP en un corto y sencillo tutorial. Este documento solamente trata de la creación de páginas web dinámicas con PHP, aunque PHP no solamente es capaz de crear páginas web. Consulte la sección titulada¿Qué puede hacer PHP?para más información.

Las páginas web que usan PHP se tratan igual que páginas HTML comunes y corrientes, y se pueden crear y editar de la misma manera que normalmente se crean páginas HTML.


¿Qué necesito?

En este manual se asume que se cuenta con un servidor que tiene soporte activado para PHP y que todos los ficheros con la extensión.phpson tratados por PHP. En la mayoría de servidores, esta es la extensión predeterminada para los ficheros de PHP, aunque puede preguntar al administrador de su servidor para estar seguro. Si el servidor tiene soporte para PHP, entonces no es necesario hacer nada. Simplemente cree sus ficheros.php, guárdelos en su directorio web y el servidor los analizará por usted. No hay necesidad de compilar nada o instalar otras herramientas. Piense en estos ficheros habilitados para PHP como simples ficheros HTML con el añadido de una nueva familia de etiquetas mágicas que permiten todo tipo de cosas.

Digamos que quiere ahorrar el preciado ancho de banda y trabajar localmente. En este caso, querrá instalar un servidor web, como» Apache, y por supuesto» PHP. Lo más seguro es que también quiera instalar una base de datos como» MySQL.

Puede instalarlos de forma independiente o bien puede elegir una manera más sencilla. Este manual contieneInstrucciones de instalación de PHP(asumiendo que tiene algún tipo de servidor web ya configurado). Si tuviera problemas con la instalación, sugerimos que formule sus preguntas en nuestra» lista de correo de instalación. Si elige la manera más sencilla,» localice un paquete preconfiguradopara su sistema operativo, el cual instala automáticamente todo esto con únicamente unos pocos clics de ratón. Es sencillo configurar un servidor web con soporte para PHP en cualquier sistema operativo, incluyendo MacOSX, Linux y Windows. En Linux, podría encontrar útil» rpmfindy» PBonepara localizar los RPM. También puede visitar» apt-getpara buscar paquetes para Debian..



Su primera página con PHP

Comience por crear un fichero llamadohola.phpy póngalo en el directorio raíz de su servidor web (DOCUMENT_ROOT) con el siguiente contenido:

Ejemplo #1 Nuestro primer script de PHP:hola.php

<html>
<head>
<title>Prueba de PHP</title>
</head>
<body>
<?phpecho'<p>Hola Mundo</p>';?>
</body>
</html>

Utilice su navegador web para acceder al fichero con el URL de su servidor, finalizado con la referencia al fichero/hola.php. Si está programando localmente, este URL será algo parecido ahttp://localhost/hola.phpohttp://127.0.0.1/hola.php, pero esto depende de la configuración de su servidor web. Si todo está configurado correctamente, el fichero será analizado por PHP y se enviará el siguiente contenido a su navegador:

<html>
 <head>
  <title>Prueba de PHP</title>
 </head>
 <body>
 <p>Hola mundo</p>
 </body>
</html>

Este programa es extremadamente simple y realmente no es necesario utilizar PHP para crear una página como esta. Lo único que muestra es:Hola mundoempleando la sentenciaechode PHP. Observe que el ficherono necesita ser ejecutableo especial de ninguna forma. El servidor reconoce que este fichero necesita ser interpretado por PHP debido al empleo de la extensión ".php", ya que el servidor está configurado para enviarlo a PHP. Piense como si fuera un fichero HTML normal que tiene una serie de etiquetas especiales disponibles con las que puede hacer muchas cosas interesantes.

Si intentó usar este ejemplo y no produjo ningún resultado, se le preguntó si deseaba descargar el fichero, o se mostró todo el fichero como texto, lo más seguro es que PHP no se encuentre habilitado en su servidor o no esté configurado adecuadamente. Pídale a su administrador que lo habilite utilizando el capítuloInstalacióndel manual. Si está trabajando localmente, lea también el capítulo dedicado a la instalación para asegurarse de que todo esté configurado adecuadamente. Asegúrese de que está accediendo al fichero mediante http y que el servidor muestre el resultado. Si está abriendo el fichero desde el sistema de ficheros, probablemente no será analizado por PHP. Si el problema persiste, no dude en usar alguna de las múltiples opciones del» Soporte para PHP.

El objetivo de este ejemplo es el formato de las etiquetas especiales de PHP. En este ejemplo utilizamos<?phppara indicar el inicio de una etiqueta de PHP. Después ponemos la sentencia y abandonamos el modo PHP añadiendo la etiqueta de cierre?>. De esta manera, se puede entrar y salir del modo PHP en un fichero HTML cada vez que se quiera. Para más información, lea la sección del manual tituladaSintaxis básica de PHP.

Nota:Una observación sobre los avances de línea

Los avances de línea tienen poco sentido en HTML, aunque sigue siendo buena idea hacer que el código HTML se vea limpio y claro poniendo avances de línea. PHP automáticamente eliminará los avances de línea que estén después de una etiqueta de cierre?>. Esto puede ser muy útil al poner muchos bloques de PHP o incluir ficheros que contienen PHP y que se supone que no deben mostrar nada. Al mismo tiempo, puede resultar un poco confuso. Se puede poner un espacio después de la etiqueta de cierre?>para mostrar forzosamente un espacio y un avance de línea, o se puede poner un avance de línea explícito en el último echo/print dentro del bloque de PHP.

Nota:Una observación sobre los editores de texto

Hay muchos editores de texto y Entornos de Desarrollo Integrados (IDE por sus siglas en Inglés) que se pueden emplear para crear, editar, y gestionar ficheros de PHP. Se puede encontrar una lista parcial de estos en» Lista de editores de PHP. Si desea recomendar un editor, por favor visite la página mencionada anteriormente y pregunte al mantenedor de la página para que lo incluya en la lista. Contar con un editor que resalte la sintaxis puede ser de mucha ayuda.

Nota:Una observación sobre los procesadores de texto

Los procesadores de texto como StarOffice Writer, Microsoft Word y Abiword no son buenas opciones para editar ficheros de PHP. Si desea utilizar uno de estos programas para probar este script, asegúrese de guardar el documento comotexto sin formato, o de lo contrario, PHP no será capaz de leerlo y ejecutarlo.

Nota:Una observación sobre el Bloc de Notas de Windows

Si escribe sus scripts de PHP usando el Bloc de Notas de Windows, debe asegurarse de que sus ficheros sean guardados con la extensión.php. (El Bloc de Notas automáticamente añade la extensión.txta los ficheros a menos que siga los siguientes pasos para prevenirlo). Cuando guarde el fichero y el programa le pregunte qué nombre desea dar al fichero, entrecomille el nombre (es decir, "hola.php"). Una alternativa es hacer clic en el menú desplegable "Documentos de Texto (*.txt)" del cuadro de diálogo "Guardar como", y cambiar a la opción "Todos los archivos (*.*)". Aquí puede escribir el nombre del fichero sin las comillas.

Ahora que ha creado un pequeño script de PHP que funciona correctamente, es hora de crear el script de PHP más famoso: hacer una llamada a la funciónphpinfo()para obtener mucha información útil acerca de su sistema y configuración, como lasvariables predefinidasdisponibles, los módulos de PHP cargados, y los ajustes deconfiguración. Tómese algo de tiempo para revisar esta importante información.

Ejemplo #2 Obtener la información del sistema desde PHP

<?php phpinfo();?>



Algo útil

Hagamos ahora algo que puede ser más útil. Vamos a comprobar qué tipo de navegador está utilizando el usuario visitante. Para hacerlo, vamos a comprobar el string del agente de usuario que el navegador envía como parte de la petición HTTP. Esta información es almacenada en unavariable. En PHP, las variables siempre comienzan con un signo de dólar. La variable que nos interesa ahora es$_SERVER['HTTP_USER_AGENT'].

Nota:

$_SERVERes una variable especial reservada por PHP que contiene toda la información del servidor web. Es conocida como una superglobal. Consulte la página del manual sobreSuperglobalespara más información.

Para mostrar esta variable, se puede hacer simplemente:

Ejemplo #1 Imprimir una variable (elemento de array)

<?php
echo$_SERVER['HTTP_USER_AGENT'];
?>

Un ejemplo del resultado de este script podría ser:


Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)

Hay muchostiposde variables en PHP. En el ejemplo anterior se muestra un elemento de unArray. Los arrays pueden ser muy útiles.

$_SERVERes simplemente una variable que se encuentra disponible automáticamente en PHP. Se puede encontrar una lista en la secciónVariables reservadasdel manual, o se puede obtener una lista completa observando la salida de la funciónphpinfo()usada en el ejemplo de la sección anterior.

Puede usar múltiples sentencias de PHP dentro de una etiqueta de PHP y crear pequeños bloques de código que realicen más que un simple 'echo'. Por ejemplo, si se quisiera detectar el uso de Internet Explorer, se podría hacer algo así:

Ejemplo #2 Ejemplo usandoestructuras de controlyfunciones

<?php
if (strpos($_SERVER['HTTP_USER_AGENT'],'MSIE') !==FALSE) {
echo
'Está usando Internet Explorer.<br />';
}
?>

Un ejemplo del resultado de este script sería:

Está usando Internet Explorer.<br />

Aquí hemos introducido un par de conceptos nuevos. Tenemos una sentenciaif. Si está familiarizado con la sintaxis básica del lenguaje C, debería parecerle lógico. De lo contrario, probablemente debería conseguir un libro que le introduzca a PHP, y leer el primer par de capítulos, o leer la parte del manual tituladaReferencia del lenguaje.

El segundo concepto que introducimos fue la función llamada astrpos().strpos()es una función integrada en PHP que busca un string dentro de otro. En este caso estamos buscando'MSIE'(también llamado aguja) dentro de$_SERVER['HTTP_USER_AGENT'](también llamado pajar). Si el string se encuentra dentro del pajar, la función devuelve la posición de la aguja relativa al inicio del pajar. De lo contrario, devuelvefalse. Si no devuelvefalse, la expresiónifse evalúa comotruey se ejecuta el código entre llaves {}. De lo contrario, el código no será ejecutado. Tómese la libertad de crear ejemplos similares, conif,else, y otras funciones comostrtoupper()ystrlen(). Cada página del manual relacionada también contiene ejemplos. Si no está seguro de cómo usar estas funciones, es recomendable que lea las páginas del manual sobreCómo interpretar una definición de funcióny la sección sobreFunciones de PHP.

Podemos dar un paso más y mostrar cómo se puede entrar y salir del modo PHP incluso en medio de un bloque de código de PHP:

Ejemplo #3 Mezcla de los modos HTML y PHP

<?php
if (strpos($_SERVER['HTTP_USER_AGENT'],'MSIE') !==FALSE) {
?>
<h3>strpos() debe haber devuelto no falso</h3>
<p>Está usando Internet Explorer</p>
<?php
} else {
?>
<h3>strpos() debe haber devuelto falso</h3>
<p>No está usando Internet Explorer</p>
<?php
}
?>

Un ejemplo del resultado del script podría ser:

<h3>strpos() debe haber devuelto no falso</h3>
<p>Está usando Internet Explorer</p>

En vez de usar una sentencia echo de PHP para mostrar algo, salimos del modo PHP y enviamos solamente HTML. Este es un punto muy importante y potente que se ha de observar aquí, y es que la fluidez lógica del script permanece intacta. Solamente uno de los bloques HTML terminará siendo enviado al navegador dependiendo del resultado destrpos(). En otras palabras, depende de si el stringMSIEfue encontrada o no.



Tratar con formularios

Otra de las características más potentes de PHP es la forma de gestionar formularios HTML. El concepto básico que es importante entender es que cualquier elemento de un formulario estará disponible automáticamente en sus scripts de PHP. Por favor, lea la sección del manual sobreVariables desde fuentes externaspara obtener más información y ejemplos sobre cómo usar formularios con PHP. Observemos un ejemplo:

Ejemplo #1 Un formulario HTML sencillo

<form action="accion.php" method="post">
 <p>Su nombre: <input type="text" name="nombre" /></p>
 <p>Su edad: <input type="text" name="edad" /></p>
 <p><input type="submit" /></p>
</form>

No hay nada especial en este formulario. Es solamente un formulario HTML sin ninguna clase de etiqueta especial. Cuando el usuario rellena este formulario y oprime el botón de envío, se llama a la páginaaccion.php. En este fichero se podría escribir algo así:

Ejemplo #2 Mostrar información de nuestro formulario

Hola<?phpechohtmlspecialchars($_POST['nombre']);?>.
Usted tiene<?phpecho (int)$_POST['edad'];?>años.

Un ejemplo del resultado de este script podría ser:

Hola José. Usted tiene 22 años.

Excepto las partes dehtmlspecialchars()y de(int), debería ser obvio qué es lo que hace el código.htmlspecialchars()garantiza que cualquier carácter que sea especial en html se codifique adecuadamente, de manera que nadie pueda inyectar etiquetas HTML o Javascript en la página. El campo edad, ya que sabemos que es un número, podemosconvertirloa un valor de tipointegerque automáticamente se deshará de cualquier carácter no numérico. También se puede hacer lo mismo con PHP con la extensiónfilter. Las variables$_POST['nombre']y$_POST['edad']son establecidas automáticamente por PHP. Anteriormente hemos usado la superglobal$_SERVER; arriba introdujimos la superglobal$_POST, la cual contiene todos los datos de POST. Observe que elmétodode nuestro formulario es POST. Si hubiésemos usado el métodoGET, nuestra información estaría en su lugar en la superglobal$_GET. También se podría usar la superglobal$_REQUEST, si no le preocupa la fuente de los datos solicitados. Contiene toda la información de los datos de GET, POST y COOKIE mezclada.

En PHP, también puede tratar con entradas de XForms; aunque probablemente al principio se sienta cómodo con los formularios de HTML, los cuales están ampliamente respaldados. A pesar de que trabajar con XForms no es para principiantes, podrían interesarle. Si es así, en la sección de características hay unapequeña introducción a la manipulación de datos recibidos desde XForms.



¿Y ahora qué?

Con sus nuevos conocimientos debería ser capaz de entender la mayoría del manual y los diversos scripts de ejemplo disponibles en los archivos de ejemplos.

Para ver varias presentaciones que muestran más acerca de lo que puede hacer PHP, véase el Sitio de Material de Conferencias de PHP:» http://talks.php.net/





Instalación y configuración


Consideraciones generales de instalación

Antes de empezar con la instalación, primero necesita saber para qué quiere utilizar PHP. Existen tres campos principales donde se puede utilizar PHP tal y como se describe en la sección:¿Qué se puede hacer con PHP?

  • Aplicaciones web y sitios web (scripting del lado del servidor)
  • Scripting en la línea de comandos
  • Aplicaciones de escritorio (GUI)

Para la primera forma mencionada, que es la más común, se necesitan tres cosas: PHP, un servidor web y un navegador web. Seguramente ya disponga del navegador web y, dependiendo de la configuración del sistema operativo, quizá ya tenga un servidor web (p.ej. Apache en Linux y macOS; IIS en Windows). También puede alquilar espacio web en una empresa. De esta forma, no se necesita instalar nada, solo tiene que escribir los scripts de PHP, subirlos al servidor que alquile y ver los resultados en su navegador.

En caso de configurar el servidor y PHP por su cuenta, existen dos opciones para el modo de conectar PHP con el servidor. Para muchos servidores, PHP tiene un módulo de interfaz directo (también llamado SAPI). Entre estos servidores se incluyen Apache, Microsoft Internet Information Server, Netscape y iPlanet. Muchos otros servidores tienen soporte para ISAPI, el módulo de interfaz de Microsoft (OmniHTTPd por ejemplo). Si PHP no tiene soporte para el módulo de su servidor web, siempre puede usarlo como procesador CGI o FastCGI. Esto significa configurar el servidor para usar el CGI ejecutable de PHP para procesar cada una de las peticiones a ficheros PHP en el servidor.

Si también está interesado en usar PHP bajo la línea de comandos (p.ej. escribir scripts que autogeneran imágenes de forma offline, o procesar ficheros de texto dependiendo de los argumentos que se les pasen), siempre necesitará el ejecutable de línea de comandos. Para más información, lea la sección sobreescribir aplicaciones PHP desde la línea de comandos. En este caso, no se necesita ningún servidor o navegador.

Con PHP también se pueden escribir aplicaciones GUI de escritorio usando la extensión PHP-GTK. Este enfoque no tiene nada que ver con escribir páginas web, ya que no se muestra nada de HTML, pero gestiona ventanas y objetos dentro de ellas. Para más información acerca de PHP-GTK, por favor» visite el sitio dedicado a esta extensión. PHP-GTK no está incluido en la distribución oficial de PHP.

De aquí en adelante, esta sección trata de la configuración de PHP para servidores web sobre Unix y Windows con interfaces de módulo de servidor y ejecutables CGI. También se puede encontrar información sobre ejecutables de línea de comandos en las siguientes secciones.

El código fuente de PHP y las distribuciones binarias para Windows pueden encontrarse en» https://www.php.net/downloads.php. Recomendamos elegir un» sitio alternativocercano para descargar las distribuciones.



Instalación sobre sistemas Unix

Tabla de contenidos

Esta sección le guiará a través de la configuración general e instalación de PHP sobre sistemas Unix. Asegúrese de investigar cualquier sección específica a su plataforma o servidor web antes de comenzar el proceso.

Tal como el manual lo esboza en la secciónConsideraciones generales de instalación, se está tratando principalmente con configuraciones de PHP centradas en web en esta sección, aunque también se cubrirá el preparar PHP para usarse en línea de comando.

Existen varias maneras de instalar PHP para la plataforma Unix, ya sea con un proceso de compilar y configurar, o a través de varios métodos pre-empaquetados. Esta documentación está enfocada principalmente alrededor del proceso de compilar y configurar PHP. Muchos sistemas estilo Unix tienen algún tipo de sistema de instalación de paquetes. Esto puede ayudar en preparar una configuración standard, pero si se requiere tener un conjunto diferente de características (tales como un servidor seguro, o un manejador diferente de base de datos), podría ser necesario construir PHP y/o el servidor web. Si no se está familiarizado con la construcción y el compilado de su propio software, vale la pena revisar para ver si alguien ya ha construido una versión empaquetada de PHP con las características que se necesitan.

Conocimientos y software necesarios para compilar:

  • Habilidades básicas en Unix (ser capaz de operar "make" y un compilador de C)
  • Un compilador ANSI C
  • Un servidor web
  • Cualquier componente específico para módulos (tales comoGD,PDFlibs, etc.)

Cuando compile directamente de una fuente Git o después de realizar modificaciones usted necesita también:

  • autoconf: 2.59+ (for PHP >= 7.0.0), 2.64+ (for PHP >= 7.2.0)
  • automake: 1.4+
  • libtool: 1.4.x+ (excepto 1.4.2)
  • re2c: 0.13.4+
  • bison:
    • PHP 7.0 - 7.3: 2.4 o superior (incluyendo Bison 3.x)
    • PHP 7.4: > 3.0

El proceso inicial de preparación y configuración de PHP es controlado por el uso de las opciones de línea de comando del scriptconfigure. Es posible obtener una lista de todas las opciones disponibles junto con una descripción corta ejecutando./configure --help. El manual documenta las diferentes opciones por separado. Se encontrarán lasopciones principales en el apéndice, mientras que las diferentes opciones específicas de las extensiones se describen en las páginas de referencia.

Cuando PHP está configurado, se está listo para compilar el módulo y/o ejecutables. El comandomakedebería hacerse cargo de esto. Si falla y no se puede encontrar el porque, véase lasección de problemas.

Nota:

Algunos sistemas UNIX (como OpenBSD y SELinux) pueden deshabilitar el mapeo de páginas tanto en escritura como lectura por razones de seguridad, Lo que se llama PaX MPROTECT o W^X protección contra violaciones. Este tipo de mapeado de memoria es, sin embargo, necesario para el soporte JIT PCRE, por lo que bien PHP debe ser compiladosin soporte PCRE's JIT, o el binario ha de ser cargado en lista blanca por cualquier medio proporcionado por el sistema.

Nota:La compilación cruzada para ARM con el toolchain de herramientas de Android no es compatible actualmente.


Apache 2.x sobre sistemas Unix

Esta sección contiene notas y consejos específicos a las instalaciones de Apache 2.x de PHP sobre sistemas Unix.

Advertencia

No se recomienda utilizar un MPM threaded en producción con Apache 2. Use MPM prefork, que es el MPM por defecto en Apache 2.0 y 2.2. Para información sobre cómo, lea la correspondiente entrada de la FAQ sobre utilizarApache2 con un MPM threaded

La» Documentación de Apachees la fuente de información más autorizada acerca del servidor Apache 2.x. Ahí se puede encontrar más información acerca de las opciones de instalación.

La versión más reciente de Apache HTTP Server puede obtenerse del» Sitio de descargas de Apache, y una versión apropiada de PHP de los lugares anteriormente mencionados. Esta guía rápida solamente cubre lo básico para comenzar con Apache 2.x y PHP. Para obtener más información lea la» Documentación de Apache. Los números de versión han sido omitidos aquí, para asegurar que las instrucciones no sean incorrectas. En los ejemplos siguientes, 'NN' deberá ser reemplazado con la versión específica de Apache que se está utilizando.

Existen actualmente dos versiones de Apache 2.x - está la 2.0 y la 2.2. Mientras que existen varias razones para elegir cada una, la 2.2 es actualmente la versión más reciente, y la que se recomienda, si es que esa opción está disponible. Sin embargo, las instrucciones aquí funcionarán ya sea para 2.0 ó 2.2.

  1. Obténgase el servidor HTTP Apache de la ubicación listada con anterioridad, y desempáquese:

    gzip -d httpd-2_x_NN.tar.gz
    tar -xf httpd-2_x_NN.tar
    
  2. De la misma manera, obtener y desempacar las fuentes de PHP:

    gunzip php-NN.tar.gz
    tar -xf php-NN.tar
    
  3. Compilar e instalar Apache. Consúltese la documentación de instalación de Apache para mayores detalles sobre la compilación de Apache.

    cd httpd-2_x_NN
    ./configure --enable-so
    make
    make install
    
  4. Ahora se tiene Apache 2.x.NN disponible debajo de /usr/local/apache2, configurado con soporte para módulos cargables y con el MPM (Módulo de multiproceso) prefork estándar. Para probar la instalación úsese el procedimiento para iniciar el servidor Apache, por ej.:

    /usr/local/apache2/bin/apachectl start
    
    y deténgase el servidor para proceder con la configuración para PHP:
    /usr/local/apache2/bin/apachectl stop
    

  5. Ahora, configure y compile PHP. Aquí es donde se personaliza PHP con varias opciones, como qué extensiones se han de habilitar. Ejecute ./configure --help para obtener una lista de opciones disponibles. En el ejemplo se realiza un simple configure con soporte para Apache 2 y MySQL.

    Si se compila Apache a partir de los fuentes, tal como se describe anteriormente, el siguiente ejemplo coincidirá con la trayectoria para apxs, pero si se ha instalado Apache de alguna otra manera, será necesario ajustar la trayectoria a apxs apropiadamente. Nótese que algunas distribuciones pueden renombrar apxs cómo apxs2.

    cd ../php-NN
    ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql
    make
    make install
    

    Si se decide a cambiar las opciones de configuración después de la instalación, se deben volver a ejecutar los pasos configure, make, y make install. Solamente se necesita reiniciar apache para que el nuevo módulo tenga efecto. Una recompilación de Apache no es necesaria.

    Nótese que a menos que se indique lo contrario, 'make install' también instalará PEAR, varias herramientas de PHP tales como phpize, instalará la interfaz de línea de comando (CLI) de PHP, y más.

  6. Configurar php.ini

    cp php.ini-development /usr/local/lib/php.ini
    

    Se puede editar el fichero .ini para fijar las opciones de PHP. Si se prefiere tener php.ini en otra ubicación, utilice --with-config-file-path=/alguna/trayectoria en el paso 5.

    Si en vez de eso se elige php.ini-production, asegúrese de leer la lista de cambios al interior, ya que afectan como se comporta PHP.

  7. Edítese httpd.conf para cargar el módulo PHP. La trayectoria a la derecha de la sentencia LoadModule debe apuntar a la trayectoria del módulo PHP en el sistema. El make install anterior podría ya haber agregado esto automáticamente, pero asegúrese de revisar.

    Para PHP 7:

    LoadModule php7_module modules/libphp7.so

    Para PHP 5:

    LoadModule php5_module modules/libphp5.so
  8. Indicar a Apache que procese ciertas extensiones como PHP. Por ejemplo, hágase que Apache procese ficheros .php como PHP. En vez de solamente utilizar la directiva de Apache AddType, se desea evitar subidas de ficheros potencialmente peligrosas y que ficheros creados tal como exploit.php.jpg sean ejecutados como PHP. Utilizando este ejemplo, se puede hacer que cualquier extensión o extensiones sean procesadas como PHP simplemente añadiéndolas. Se agregará .php para demostrarlo.

    <FilesMatch \.php$>
        SetHandler application/x-httpd-php
    </FilesMatch>

    O, si se deseara permitir que ficheros .php, .php2, .php3, .php4, .php5, .php6, y .phtml fuesen ejecutados como PHP, pero nada más, se utilizaría esto:

    <FilesMatch "\.ph(p[2-1]?|tml)$">
        SetHandler application/x-httpd-php
    </FilesMatch>

    Y para permitir que ficheros .phps sean manejados por el filtro de fuentes de php, y desplegado como código fuente con sintaxis resaltada, se utiliza esto:

    <FilesMatch "\.phps$">
        SetHandler application/x-httpd-php-source
    </FilesMatch>

    mod_rewrite puede ser utilizado para permitir que cualquier fichero .php arbitrario sea desplegado como código fuente con sintaxis resaltada, sin tener que renombrarlo o copiarlo a un fichero .phps:

    RewriteEngine On
    RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]

    El filtro de código fuente php no debe habilitarse en sistemas de producción, donde podría exponer información confidencial o de alguna otra manera sensible incluida en código fuente.

  9. Utilícese el procedimiento normal para iniciar el servidor Apache, por ej.:

    /usr/local/apache2/bin/apachectl start
    

    O

    service httpd restart
    

Siguiendo los pasos anteriores se tendrá corriendo un servidor web Apache2 con soporte para PHP como un móduloSAPI. Por supuesto existen muchas opciones más de configuración disponibles para Apache y PHP. Para más información teclee./configure --helpen el árbol de fuentes correspondiente.

Apache se puede compilar con soporte multihilos seleccionando elworkerMPM, en vez delpreforkMPM standard, cuando Apache se compila. Esto se realiza agregando la siguiente opción al argumento pasado a ./configure, en el paso 3 anterior:

--with-mpm=worker

Esto no debe llevarse a cabo sin ser consciente de las consecuencias de esta decisión, y tener al menos un ligero entendimiento acerca de las implicaciones. La documentación de Apache al respecto de» MPM-Modulesdiscute los MPM en forma mucho más detallada.

Nota:

LasPreguntas frecuentes de Apache MultiViewsdiscute acerca del uso de multiviews con PHP.

Nota:

Para compilar una versión multihilo de Apache, el sistema destino debe soportar hilos. En este caso, PHP también debe compilarse con la opción Zend Thread Safety (ZTS) experimental. Bajo esta configuración, no todas las extensiones se encontrarán disponibles. La configuración recomendada es compilar Apache con el MPM-modulepreforkpor omisión.



Nginx 1.4.x en sistemas Unix

Esta documentación cubre la instalación y configuración de PHP con PHP-FPM para un servidor HTTP de Nginx 1.4.x.

En esta guía se asume que se ha construido Nginx desde el código fuente, por lo que todos los ficheros binarios y de configuración están ubicados en/usr/local/nginx. Si este no es el caso y se ha obtenido Nginx a través de otros medios, consúltese la» Wiki de Nginxpara traducir este manual a una configuración propia.

Esta guía cubre la configuración básica de un servidor Nginx para procesar aplicaciones de PHP y servirlas en el puerto 80. Se recomienda estudiar la documentación de Nginx y de PHP-FPM para poder optimizar la configuración más allá del ámbito de esta documentación.

Obsérvese que en esta documentación se han reemplazado los números de versión con una 'x' para asegurarse de que sea correcta en el futuro; se han de reemplazar estos con los números de versión correspondiente cuando sea necesario.

  1. Se recomienda visitar la página de» instalaciónde la Wiki de Nginx para obtener e instalar Nginx en un sistema propio.

  2. Obtener y desempaquetar el código fuente de PHP:

    tar zxf php-x.x.x
    
  3. Configurar y construir PHP. Aquí es donde se personaliza PHP con varias opciones, como qué extensiones se habilitarán. Ejecutar ./configure --help para enumerar las opciones disponibles. En este ejemplo se realiza una configuración sencilla con soporte para PHP-FPM y MySQL.

    cd ../php-x.x.x
    ./configure --enable-fpm --with-mysql
    make
    sudo make install
    
  4. Obtener y mover los ficheros de configuración a sus ubicaciones correctas

    cp php.ini-development /usr/local/php/php.ini
    cp /usr/local/etc/php-fpm.conf.default /usr/local/etc/php-fpm.conf
    cp sapi/fpm/php-fpm /usr/local/bin
    
  5. Es importante prevenir que Nginx pase peticiones al «backend» de PHP-FPM si el fichero no existe, evitando así la inyección arbitraria de scripts.

    Esto se puede corregir estableciendo la directivacgi.fix_pathinfoa0dentro del fichero php.ini.

    Cargar el php.ini:

    vim /usr/local/php/php.ini
    

    Localizarcgi.fix_pathinfo=y modificarla como sigue:

    cgi.fix_pathinfo=0
    
  6. Se debe modificar php-fpm.conf para especificar que php-fpm debe ejecutarse como el usuario www-data y el grupo www-data antes de poder iniciar el servicio:

    vim /usr/local/etc/php-fpm.conf
    

    Buscar y modificar lo siguiente:

    ; Usuario/grupo de procesos de Unix
    ; Nota: El usuario es obligatorio. Si el grupo no se establece, se utilizará
    ;       el grupo predeterminado del usuario.
    user = www-data
    group = www-data
    

    Ahora se puede iniciar el servicio de php-fpm:

    /usr/local/bin/php-fpm
    

    Esta guía no continua configurando php-fpm; si se tiene interés en una configuración mayor de php-fpm, consulte la documentación.

  7. Ahora Nginx debe configurarse para que pueda procesar aplicaciones de PHP:

    vim /usr/local/nginx/conf/nginx.conf
    

    Modificar el bloque de ubicaciones predeterminado para que intente servir ficheros .php:

    location / {
        root   html;
        index  index.php index.html index.htm;
    }

    El siguiente paso es asegurarse de que los ficheros .php se pasan al «backend» de PHP-FPM. Bajo el bloque de ubicaciones predeterminado de PHP comentado, añadir lo siguiente:

    location ~* \.php$ {
        fastcgi_index   index.php;
        fastcgi_pass    127.0.0.1:9000;
        include         fastcgi_params;
        fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
        fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
    }

    Reiniciar Nginx.

    sudo /usr/local/nginx/sbin/nginx -s stop
    sudo /usr/local/nginx/sbin/nginx
    
  8. Crear un fichero de prueba

    rm /usr/local/nginx/html/index.html
    echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php
    

    Ahora, navegar a http://localhost. phpinfo() debería mostrarse.

Siguiendo los pasos anteriores se tendrá un servidor web Nginx funcionando con soporte para PHP como móduloSAPI. Por supuesto, existen muchas más opciones de configuración disponibles para Nginx y PHP. Para más información, teclear./configure --helpen el árbol de código fuente correspondiente.



Lighttpd 1.4 en sistemas Unix

Esta sección contiene anotaciones y consejos específicos para la instalación de PHP en Lighttpd 1.4 para sistemas Unix.

Por favor, antes de continuar consulte el»  sistema de seguimiento de Lighttpdpara saber cómo instalar Lighttpd apropiadamente.

La SAPI recomendada para conectar PHP a Lighttpd es Fastcig. Esta SAPI viene habilitada por omisión en php-cgi PHP 5.3. En versiones anteriores debe configurarse PHP con --enable-fastcgi. Para verificar que PHP tiene fastcgi habilitado,php -vdebe contenerPHP 5.2.5 (cgi-fcgi)En versiones anteriores a PHP 5.2.3, fastcgi estaba habilitado en el binario de php (no había php-cgi).

Permitiendo que Lighttpd lance procesos de php

Para configurar Lighttpd para que se conecte a php y lance procesos fastcgi, debe editar lighttpd.conf. Se recomienda utilizar sockets para conectar fastcgi a los procesos del sistema local.

Ejemplo #1 Extracto de lighttpd.conf

server.modules += ( "mod_fastcgi" )

fastcgi.server = ( ".php" =>
  ((
    "socket" => "/tmp/php.socket",
    "bin-path" => "/usr/local/bin/php-cgi",
    "bin-environment" => (
      "PHP_FCGI_CHILDREN" => "16",
      "PHP_FCGI_MAX_REQUESTS" => "10000"
    ),
    "min-procs" => 1,
    "max-procs" => 1,
    "idle-timeout" => 20
  ))
)

La directiva bin-path permite a lighttpd lanzar procesos fastcgi dinámicamente. PHP creará nuevos procesos hijos según se especifique en la variable de entorno PHP_FCGI_CHILDREN. La directiva "bin-environment" establece el entorno de los nuevos procesos. Cada vez que se alcance un determinado número de peticiones, determinado por PHP_FCGI_MAX_REQUEST, se matará un proceso. Las directivas "min-procs" y "max-procs" deben, por norma general, evitarse con PHP. PHP gestiona sus propios hijos, de forma que cachés como APC sólo estarán disponibles para los procesos gestionados por PHP. Si se establece "min-procs" a un número superior a 1, el número total de procesos oyentes en php se multiplicará por PHP_FCGI_CHILDREN (2 min-procs * 16 hijos produce 32 oyentes).

Lanzando procesos con spawn-fcgi

Lighttpd contiene el programa spawn-fcgi que facilita lanzar procesos fastcgi.

Lanzando procesos php-cgi

Pese a que es más laborioso, es posible lanzar procesos sin spawn-fcgi. La variable de entorno PHP_FCGI_CHILDREN controla cuántos procesos hijo de PHP se lanzarán para manejar las peticiones entrantes. PHP_FCGI_MAX_REQUESTS determinará el tiempo de vida (en peticiones) de cada proceso hijo. Aquí se muestra un script en bash que asiste en la creación de procesos php.

Ejemplo #2 Lanzando oyentes FastCGI

#!/bin/sh

# Ubicación del binario php-cgi
PHP=/usr/local/bin/php-cgi

# Ubicación del fichero PID
PHP_PID=/tmp/php.pid

# Enlazando a una dirección
#FCGI_BIND_ADDRESS=10.0.1.1:10000
# Enlazando a un socket de dominio
FCGI_BIND_ADDRESS=/tmp/php.sock

PHP_FCGI_CHILDREN=16
PHP_FCGI_MAX_REQUESTS=10000

env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
       PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
       $PHP -b $FCGI_BIND_ADDRESS &

echo $! > "$PHP_PID"

Conexión a instancias FCGI remotas

Para poder tener aplicaciones escalables, pueden lanzarse instancias de fastcgi en múltiples equipos remotos.

Ejemplo #3 Conexión a instancias de php-fastcgi remotas

fastcgi.server = ( ".php" =>
   (( "host" => "10.0.0.2", "port" => 1030 ),
    ( "host" => "10.0.0.3", "port" => 1030 ))
)


Servior web LiteSpeed/OpenLiteSpeed en sistemas Unix

LiteSpeed ​​PHP (LSPHP) es una compilación optimizada de PHP creada para funcionar con los productos de LiteSpeed a través de LiteSpeed ​​SAPI. LSPHP se ejecuta como su propio proceso y tiene su propio binario independiente, el cual puede usarse como un simple binario de línea de comandos para ejecutar scripts PHP desde la terminal.

LSAPI es una API altamente optimizada que permite la comunicación entre LiteSpeed y motores web de terceros. Su protocolo es similar al FCGI, pero más eficiente.

Esta documentación abarcará la instalación y configuración de PHP con LSAPI   tanto para un servidor web LiteSpeed como para un servidor web OpenLiteSpeed.

Esta guía asumirá que LSWS u OLS están instalados con sus   rutas y banderas predeterminadas. El directorio de instalación predeterminado para ambos servidores será /usr/local/lsws y ambos se podrán ejecutar desde el subdirectorio bin.

Tenga en cuenta que a lo largo de esta documentación, los números de versión han sido   reemplazados con unaxpara garantizar que esta se mantenga correcta en el futuro. Por favor,   reemplácelos, según sea necesario, con los números de versión correspondientes.

  1. Para obtener e instalar el servidor web LiteSpeed o OpenLiteSpeed, visite la» página de instalaciónde la wiki de LiteSpeed, o la» página de instalaciónde la wiki de OpenLiteSpeed.

  2. Obtenga y descomprima el código fuente de PHP:

    mkdir /home/php
    cd /home/php
    wget http://us1.php.net/get/php-x.x.x.tar.gz/from/this/mirror
    tar -zxvf php-x.x.x.tar.gz
    cd php-x.x.x
    
  3. Configure y compile PHP. Aquí es donde PHP se puede personalizar con varias opciones,     como pudieran ser las extensiones que se habilitarán. Ejecute ./configure --help para obtener una lista de     opciones. En el ejemplo, utilizaremos las opciones de configuración recomendadas predeterminadas para     el servidor web LiteSpeed:

    ./configure ... '--with-litespeed'
    make
    sudo make install
    
  4. Compruebe la instalación de LSPHP

    Una de las formas más simples de verificar si la instalación de PHP fue exitosa     es ejecutar el siguiente código:

    cd /usr/local/lsws/fcgi-bin/
    ./lsphp5 -v
    

    Dicho código debería devolver información sobre la nueva compilación de PHP:

    PHP 5.6.17 (litespeed) (built: Mar 22 2016 11:34:19)
    Copyright (c) 1997-2014 The PHP Group
    Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies
    

    Observe el textolitespeedentre paréntesis. Esto significa que el binario de PHP ha sido     construido con soporte para LSAPI.

Siguiendo los pasos anteriores, el servidor web LiteSpeed / OpenLiteSpeed debería   encontrarse ejecutándose con soporte para PHP como extensión SAPI. Hay muchos más   opciones de configuración disponibles para LSWS / OLS y PHP. Para más información,   eche un vistazo a la wiki de LiteSpeed sobre» PHP.

Usando LSPHP desde la línea de comando:

El modo de línea de comandos LSPHP (LSAPI + PHP) se utiliza para procesar scripts PHP que se ejecutan   en un servidor remoto que no necesariamente tiene un servidor web en ejecución. Se utiliza   para procesar scripts PHP que residen en un servidor web local (separado). Esta configuración es   adecuada para la escalabilidad del servicio, ya que el procesamiento de PHP se descarga a un servidor remoto.

Inicie lsphp desde la línea de comandos en un servidor remoto:   LSPHP es un ejecutable y puede iniciarse manualmente y vincularse a IPv4, IPv6 o   direcciones de socket de dominio Unix con la opción de línea de comandos -b socket_address

Ejemplos:

Haga que LSPHP utilice el puerto 3000 en todas las direcciones IPv4 e IPv6:

/path/to/lsphp -b [::]:3000

Haga que LSPHP utilice el puerto 3000 en todas las direcciones IPv4:

/path/to/lsphp -b *:3000

Haga que LSPHP utilice la dirección 192.168.0.2:3000:

/path/to/lsphp -b 192.168.0.2:3000

Haga que LSPHP acepte solicitudes en el socket de dominio Unix/tmp/lsphp_manual.sock:

/path/to/lsphp -b /tmp/lsphp_manual.sock

Las variables de entorno se pueden agregar antes del ejecutable LSPHP:

PHP_LSAPI_MAX_REQUESTS=500 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b IP_address:port

Actualmente, LiteSpeed PHP se puede usar con el servidor web LiteSpeed, OpenLiteSpeed y Apache mod_lsapi. Para pasos sobre configuración del lado del servidor, visite las páginas wiki de» LiteSpeedy» OpenLiteSpeed.

LSPHP también se puede instalar de otras formas:

CentOS: En CentOS, LSPHP puede ser instalado tanto desde el repositorio de LiteSpeed como desde el de Remi utilizando» RPM.

Debian: En Debian, LSPHP puede ser instalado desde el repositorio de LiteSpeed Repository utilizando» apt.

cPanel: Visite la respectiva» página de la wikisobre cómo instalar LSPHP en cPanel y LSWS/OLS usando EasyApache 4.

Plesk: Plesk puede ser usado con LSPHP en CentOS, CloudLinux, Debian, y Ubuntu. Para más detalles en este tema, visite la correspondiente» página de la wiki



CGI y configuraciones de línea de comandos

Por defecto, PHP se construye como un programaCLIyCGI, que puede ser utilizado para el procesamiento de CGI. Si está ejecutando un servidor web PHP tiene soporte para los módulos, por lo general debe irse por esta solución por razones de rendimiento. Sin embargo, la versión CGI permite a los usuarios ejecutar diferentes páginas con PHP bajo diferentes identificadores de usuarios.

Advertencia

Al usar el modo CGI, su servidor esta expuesto a diferentes ataques. Por favor, leer la secciónSeguridad con CGIpara aprender cómo defenderse de estos ataques.

Pruebas

Si has construido PHP como un programa CGI, puede probar su construcción escribiendomake test. Siempre es una buena idea probar su construcción. De esta manera usted puede encontrar un problema al principio con PHP en la plataforma, en lugar de tener que luchar con él más adelante.

Utilización de variables

Algunosservidores suministrando variables de entornono se definen en las actuales» CGI/1.1 specification. Sólo las siguientes variables no se definen:AUTH_TYPE,CONTENT_LENGTH,CONTENT_TYPE,GATEWAY_INTERFACE,PATH_INFO,PATH_TRANSLATED,QUERY_STRING,REMOTE_ADDR,REMOTE_HOST,REMOTE_IDENT,REMOTE_USER,REQUEST_METHOD,SCRIPT_NAME,SERVER_NAME,SERVER_PORT,SERVER_PROTOCOL, andSERVER_SOFTWARE. Todo lo demás debe ser tratado como "extensiones de proveedor".



Notas de instalación para OpenBSD

Esta sección contiene notas y consejos específicos a la instalación de PHP sobre» OpenBSD 3.6.

Utilizando paquetes binarios

Utilizar paquetes binarios para instalar PHP sobre OpenBSD es el método más simple y recomendado. El paquete principal ha sido separado de los distintos módulos, y cada uno puede ser instalado removido independientemente de los otros. Los ficheros que se necesitan pueden ser encontrados en el CD de OpenBSD o en el sitio FTP.

El paquete principal que se necesita instalar esphp4-core-4.3.8.tgz, que contiene el motor básico (además de gettext e iconv). Seguido, tómese un vistazo a los paquetes de módulos, tales comophp4-mysql-4.3.8.tgzophp4-imap-4.3.8.tgz. Se necesita emplear el comandophpxspara activar y desactivar estos módulos en el ficherophp.ini.

Ejemplo #1 Ejemplo de instalación de paquete de OpenBSD

# pkg_add php4-core-4.3.8.tgz
# /usr/local/sbin/phpxs -s
# cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini
  (agregar mysql)
# pkg_add php4-mysql-4.3.8.tgz
# /usr/local/sbin/phpxs -a mysql
  (agregar imap)
# pkg_add php4-imap-4.3.8.tgz
# /usr/local/sbin/phpxs -a imap
  (quitar mysql a manera de prueba)
# pkg_delete php4-mysql-4.3.8
# /usr/local/sbin/phpxs -r mysql
  (instalar las librerías de PEAR)
# pkg_add php4-pear-4.3.8.tgz

Leer la página del manual» packages(7)para mas información sobre paquetes binarios en OpenBSD.

Utilizando portes

También se puede compilar PHP a partir de fuentes utilizando el» árbol de portes. Sin embargo, esto sólo se recomienda para usuarios familiarizados con OpenBSD. El porte de PHP 4 está dividido en dos subdirectorios: core y extensions. El directorio extensions genera subpaquetes para todos los módulos soportados de PHP. Si se encuentra que no se desea crear alguno de estos módulos, utilice el sabor o FLAVORno_*. Por ejemplo, para evitar compilar el módulo imap, fijar el sabor o FLAVOR ano_imap.

Problemas comunes

  • La instalación por omisión de Apache se ejecuta dentro de una» jaula chroot(2), que habrá de restringir a los script PHP el acceso a ficheros debajo de/var/www. Por lo tanto se requiere crear un directorio/var/www/tmppara que los ficheros de sesión de PHP sean almacenados, o utilizar un medio alternativo de almacenamiento de sesiones. Además, los sockets de base de datos necesitan colocarse dentro de la jaula o escuchar en la interfaz delocalhost. Se se hace uso de funciones de red, algunos ficheros de/etctales como/etc/resolv.confy/etc/servicestendrán que ser movidos a/var/www/etc. El paquete PEAR de OpenBSD automáticamente se instala dentro de los directorios correctos del chroot, así que no hace falta ninguna modificación especial ahí. Más información sobre el Apache de OpenBSD está disponible en las preguntas frecuentes OpenBSD.
  • El paquete de OpenBSD 3.6 para la extensión» gdrequiere que XFree86 sea instalado. Si no se desea utilizar algunas de las características de fuentes tipográficas que requieren de X11, es mejor instalar el paquetephp4-gd-4.3.8-no_x11.tgz.

Ediciones antiguas

Ediciones antiguas de OpenBSD utilizaban el sistema FLAVORS para compilar un PHP enlazado estáticamente. Dado que es difícil generar paquetes binarios utilizando este método, ahora es depreciado. Aún es posible utilizar los viejos árboles estables de ports si así se desea, pero carecen de soporte por parte del equipo de OpenBSD. Si se tiene algún comentario al respecto, el responsable actual del port es Anil Madhavapeddy (avsm arroba openbsd punto org).



Solarissugerencias específicas de instalación

Esta sección contiene notas y sugerencias específicas para la instalación de PHP en sistemasSolaris.

Software necesario

La instalacion Solariscarece con frecuencia de los compiladores de C y sus herramientas relacionadas. Lealas preguntas frecuentespara obtener información sobre porqué usar versiones GNU de algunas de estas herramientas.

Para descomprimir la distribución PHP se necesita

  • tar
  • gzip ó
  • bzip2

Para compilar PHP se necesita

  • gcc (recomendado, aunque puede que sirvan otros compiladores de C)
  • make
  • GNU sed

Para compilar extensiones adicionales o hackear el código PHP puede que se necesite también

  • flex (versión PHP 5.2 o posterior)
  • re2c
  • bison
  • m4
  • autoconf
  • automake
Además, usted tendrá que instalar (y posiblemente compilar) cualquier software adicional específico para la configuración, tales como Oracle o MySQL.

Empleo de paquetes

Se puede simplificar el procesao de intalación deSolarismediante el uso de pkgadd para instalar la mayoría de sus componentes necesarios. El Sistema de Empaquetado de Imagen (IPS) paraSolaris 11 Expresscontiene también la mayoría de los componentes requeridos para la instalación usando el comando pkg.



Notas de instalación en Debian GNU/Linux

Esta sección contiene notas y consejos específicos para instalar PHP sobre» Debian GNU/Linux.

Advertencia

No se ofrece soporte de builds no oficiales de terceros. Cualquier bug debe ser informado al equipo de Debian a no ser que puedan reproducirse usando los últimos builds de nuestra» zona de descargas.

Mientras que las instrucciones para construir PHP sobre Unix se aplican a Debian también, esta página del manual contiene información específica para otras opciones, tales como utilizar ya sea los comandosapt-getoaptitude. En esta página del manual estos dos comandos se pueden utilizar indistintamente.

Utilizando APT

Primero, nótese que otros paquetes relacionados podrían ser deseables comolibapache2-mod-php5para integración con Apache 2, yphp-pearpara PEAR.

Segundo, antes de instalar un paquete, es sensato asegurarse de que la lista de paquetes está al día. Típicamente, esto se realiza ejecutando el comandoapt-get update.

Ejemplo #1 Ejemplo de Instalación en Debian con Apache 2

# apt-get install php5-common libapache2-mod-php5 php5-cli

APT instalará automáticamente el módulo PHP 5 para Apache 2 junto con todas sus dependencias, y luego lo activará. Apache debería reiniciarse para que los cambios tengan efecto. Por ejemplo:

Ejemplo #2 Deteniendo e iniciando Apache una vez que PHP está instalado

# /etc/init.d/apache2 stop
# /etc/init.d/apache2 start

Un mejor control de la configuración

En la sección anterior, PHP se instaló únicamente con los módulos principales. Es muy probable que se deseen módulos adicionales, tales comoMySQL,cURL,GD, etc. Estos también pueden ser instalados vía el comandoapt-get.

Ejemplo #3 Métodos para listar paquetes relacionados con PHP 5

# apt-cache search php5
# aptitude search php5
# aptitude search php5 |grep -i mysql

Los ejemplos mostrarán una gran cantidad de paquetes incluyendo varios específicos a PHP como php5-cgi, php5-cli y php5-dev. Determine cuales son necesarios e instálelos como cualquier otro ya sea conapt-getoaptitude. Y ya que Debian realiza revisión de dependencias, preguntará por ellos, así que por ejemplo para instalar MySQL y cURL:

Ejemplo #4 Instalar PHP con MySQL, cURL

# apt-get install php5-mysql php5-curl

APT agregará automáticamente las líneas apropiadas a los diferentes ficheros relacionados conphp.inicomo/etc/php5/apache2/php.ini,/etc/php5/conf.d/pdo.ini, etc. y dependiendo de la extensión, le agregará registros similares aextension=foo.so. De cualquier manera, reiniciar el servidor web (como es Apache) es requerido antes de que estos cambios tengan efecto.

Problemas Frecuentes

  • Si los scripts de PHP no se están interpretando por el servidor web, entonces es probable que PHP no haya sido agregado al fichero de configuración del servidor web, que en Debian puede ser/etc/apache2/apache2.confo algo semejante. Véase el manual de Debian para mayores detalles.
  • Si una extensión fue aparentemente instalada y aún así las funciones no aparecen definidas, asegurar de que el fichero ini apropiado está siendo cargado y/o que el servidor web fue reiniciado después de la instalación.
  • Hay dos comandos básicos para instalar paquetes en Debian (y otras variantes de linux):apt-getyaptitude. Pero, explicar las sutiles diferencias entre estos comandos va más allá del alcance de este manual.



Instalación en Mac OS X

Tabla de contenidos

Esta sección contiene notas y sugerencias específicas para la instalación de PHP en Mac OS X. PHP se incluye con Mac, y la compilación es similar a laguía de instalación Unix.


Empleo de paquetes

Hay algunas versiones preempaquetadas y precompiladas de PHP para Mac OS X. Esto puede ayudar en la creación de una configuración estándar, pero si fuera necesario tener un conjunto diferente de características (como un servidor seguro, o un controlador de base de datos diferente), es posible que sea necesario construir PHP y/o un servidor web. Si no está familiarizado con la construcción y compilación de su propio software, vale la pena revisar si alguien ya ha construido una versión empaquetada de PHP con las características que necesita.

Los siguientes recursos ofrecen paquetes fáciles de instalar y binarios precompilados para PHP en Mac OS:



Usando el paquete PHP

PHP está incluido en los Macs desde la versión OS X 10.0.0. Habilitar PHP con el servidor web por defecto requiere descomentar unas cuantas líneas en el fichero de configuración de Apachehttpd.confdondeCGIy/oCLIestán activados por defecto (son fácilmente accesibles a través del programa Terminal).

Siguiendo las instrucciones que se ofrecen a continuación se podrá habilitar PHP de una forma rápida para un entorno de desarrollo local. Esmuy recomendabletener siempre actualizado PHP a la última versión. Como casi todo el software vivo, y PHP no es una excepción, se crean nuevas versiones para resolver errores y añadir nuevas funcionalidades. Consulte la documentación de instalación de Mac OS X adecuada para más detalles. Las siguientes instrucciones para obtener una configuración están orientadas a los principiantes que deseen obtener una configuración totalmente operativa. Se anima a todos los usuarios a compilar o instalar una nueva versión ya empaquetada.

La instalación típica es mediante mod_php. Para habilitar el paquete mod_php que viene en el Mac OS X para el servidor web Apache (el servidor web por defecto, al que se puede acceder mediante las Preferencias del Sistema) se requiere efectuar los siguientes pasos:

  1. Localizar y abrir el archivo de configuración de Apache. Por defecto, la localización de dicho fichero es:/private/etc/apache2/httpd.confMediante elFindero elSpotlightpuede ser algo complicado encontrar dicho fichero ya que por defecto es privado y pertenece al usuarioroot.

    Nota:Una forma de abrir el fichero es usando un editor de texto basado en UNIX en el Terminal, como por ejemplonano. Debido a que el fichero pertenece al usuariorootse debe emplear el comandosudopara abrirlo (como si fueramos el usuarioroot). Por ejemplo, teclée lo siguiente en elTerminal(tras lo cual le preguntará por la contraseña):sudo nano /private/etc/apache2/httpd.confComandos de nano a tener en cuenta:^w(buscar),^o(guardar), and^x(salir) donde^representa la tecla Ctrl.

    Nota:Las versiones de Mac OS X anteriores a 10.5 tienen incorporadas versiones antiguas de PHP y Apache. Por ello, es posible que el fichero de configuracion de Apache se encuentre en dichos equipos en/etc/httpd/httpd.conf.

  2. En el editor de texto, descomente las líneas (eliminando el símbolo #) que sean similares a las que se muestran a continuación (a menudo estas líneas se encuentran separadas, asi que tendrá que localizar ambas en el fichero):

    # LoadModule php5_module libexec/httpd/libphp5.so
    
    # AddModule mod_php5.c
    
    Fíjese en la localización/ruta de acceso. Cuando compile PHP en el futuro, las lineas arriba indicadas deberán ser reemplazadas o comentadas.

  3. Asegúrese que las extensiones que desee puedan ser interpretadas como PHP (por ejemplo: .php .html y .inc)

    Como las siguientes sentencias ya existían en elhttpd.conf(desde el Max Panther), una vez se habilite PHP los ficheros.phpautomáticamente seran interpretados como PHP.

    <IfModule mod_php5.c>
        # If php is turned on, we respect .php and .phps files.
        AddType application/x-httpd-php .php
        AddType application/x-httpd-php-source .phps
    
        # Since most users will want index.php to work we
        # also automatically enable index.php
        <IfModule mod_dir.c>
            DirectoryIndex index.html index.php
        </IfModule>
    </IfModule>
    

    Nota:

    Con anterioridad a OS X 10.5 (Leopard) se empaquetaba PHP 4 en lugar de PHP 5, en cuyo caso las instrucciones anteriores pueden ser ligeramente diferentes cambiando los 5 por los 4.

  4. Asegúrese que DirectoryIndex carga el fichero por defecto index deseadoEsto tambien se configura enhttpd.conf. Normalmente se usanindex.phpyindex.html. Por defectoindex.phpestá habilitado porque está incluido en la comprobación de PHP mostrada arriba. Ajuste a conveniencia.
  5. Configure la localizacion dephp.inio use el valor por defecto.Por defecto se localiza en los Mac OS X en/usr/local/php/php.iniy empleandophpinfo()se puede obtener esta información. Si no se está usandophp.ini, PHP usará los valores por defecto. Véase también las preguntas frecuentes relacionadas enfinding php.ini.
  6. Localize o configure elDocumentRootÉste es el directorio raíz de todos los ficheros web. Los ficheros en este directorio son obtenidos del servidor web a fin de que los ficheros PHP sean ejecutados como PHP antes de ser enviados al navegador. Una ruta de acceso típica es/Library/WebServer/Documentspero puede ser configurada enhttpd.conf. Como alternativa, elDocumentRootpor defecto para usuarios individuales es/Users/yourusername/Sites
  7. Cree un ficherophpinfo()

    La funciónphpinfo()muestra información sobre PHP. Considere la creación de un fichero en el DocumentRoot que contenga el siguiente código PHP:

    <?php phpinfo();?>

  8. Reinicie Apache, y cargue el fichero PHP creado arriba

    Para reiniciar, ejecutesudo apachectl gracefulen el shell o desactive/active la opción "Compartir Web" en las Preferencias del Sistema. Por defecto, cargar ficheros locales en el navegador tiene unaURLparecida a:http://localhost/info.php. Usar DocumentRoot en el directorio del usuario es otra opción, y la URL sería parecida a:http://localhost/~yourusername/info.php

CLI(oCGIen versiones antiguas) también es llamado de forma correctaphpy posiblemente existe como/usr/bin/php. Abra el Terminal, lea lasección de línea de comandodel manual de PHP, y ejecutephp -vpara comprobar la versión de PHP del binario PHP. Una llamada aphpinfo()también le mostrará esta información.



Compilar PHP en Mac OS X

Utilice laguía de instalación en Unixpara compilar PHP en OS X.




Instalación en sistemas Windows

Tabla de contenidos

Instalación de PHP en sistemas modernos de Microsoft Windows y configuración recomendada con servidores web comunes.

Las versiones oficiales de PHP en Windows se recomiendan para su uso en producción. Sin embargo, puede construir PHP desde el código fuente. Necesitará un entorno de Visual Studio. Veáse» las instrucciones de construcción paso a paso.

Uso de PHP en la línea de comandos en WindowsInstalación de PHP en Azure App Services(aka Microsoft Azure, Windows Azure, o (Windows) Azure Web Apps).


Requisitos de instalación

PHP requiere al menos Windows 2008/Vista. Ya sea 32 bits o 64 bits (AKAX86 o X64. PHP no se ejecuta en Windows RT/WOA/ARM). A partir de PHP 7.2.0 Windows 2008 y Vista ya no son soportados.

PHP requiere Visual C runtime (CRT). Muchas aplicaciones lo requieren por lo que ya esté instalado.

El Microsoft Visual C++ Redistributable para Visual Studio 2019 es adecuado para todas las versiones de PHP, véase» https://visualstudio.microsoft.com/downloads/.

Debes descargar la biblioteca x86 CRT para compilar PHP para arquitecturas x86 y x64 CRT para compilar de PHP x64.

Si CRT ya está instalado, el instalador te lo dirá y no cambiará nada.

El instalador de CRT admite los modificadores de línea de comandos /quiet y /norestart, por lo que puede ejecutar un script.



PECL

Las extensiones PECL están preconstruidas para Windows y están disponibles en:» http://windows.php.net/downloads/pecl/releases/

Algunas extensiones usan características específicas de algunos sistemas Unix y, por lo tanto, no están disponibles en Windows. Por lo demás, todas las extensiones están disponibles para Windows.



Herramientas de instalación de PHP en Windows

Herramientas de instalación de PHP

Si quiere configurar PHP y está usando IIS, la forma más fácil es usar» El instalador de la plataforma web de Microsoft (WebPI).

» XAMPP, WampServer y BitNami configurarán las aplicaciones PHP para su uso con Apache en Windows.

La configuración de Nginx en Windows requiere un poco más de configuración. Vea la» documentación de Nginxpara obtener ayuda adicional con la configuración.



Configuración recomendada en sistemas Windows

OpCache

Se recomienda habilitar OpCache. Esta extensión está incluida en PHP para Windows. Compila y optimiza scripts de PHP y los almancena en memoria caché para así no tener que compilarlos cada vez que se cargue la página.

En el php.ini, establezca

Ejemplo #1 Configuración recomendada de WinCache

zend_extension=php_opcache.dll
opcache.enable=On
opcache.cli_enable=On
Y reinice el servidor web. Para más información, véase:Configuración de OpCache

WinCache

Se recomineda que se use WinCache si se utiliza IIS, especialmente en un entorno de alojamiento web compartido o si se utuliza el almacenamiento de ficheros en red (NAS). Tenga en cuenta que WinCache ya no es compatible con PHP 8.0.0. Todas las aplicaciones de PHP se benefician automáticamente de la funcionalidad de almancenamiento en caché de WinCache. Las operaciones en el sistema de ficheros se almacenan en memoria caché. WinCache también puede almacenar en memoria caché objetos de usuario y compartirlos entre procesos dephp.exeophp-cgi.exe(objetos compartidos entre peticiones). Muchas de las grandes aplicaciones web tienen un complemento, extensión u opción de configuración para hacer uso de la caché de objetos de usuario de WinCache. Si lo que necesita es un alto rendimiento, debería utilizar la caché de objetos en sus aplicaciones. Véase:» http://pecl.php.net/package/WinCachepara descargar una DLL (o tgz) de WinCache a su directorio de extensiones de PHP (extensions_dir en el php.ini). En el php.ini, establezca

Ejemplo #2 Configuración recomendada de WinCache


extension=php_wincache.dll
wincache.fcenabled=1
wincache.ocenabled=1 ; eliminado a partir de 2.0.0.0

Para más información, Véase:Configuración WinCache

Configuración de IIS

En el Administrador de IIS, Instalar módulo FastCGI y añadir un manejador para`.php`a la ruta dePHP-CGI.exe(no dePHP.exe)

Puede usear la herramienta de línea de comandos APPCMD para configurar IIS.

Base de datos

Probablemente necesitará un servidor de bases de datos. Las bases de datos populares proporcionan extensiones de PHP para utillzarlas. Si su sitio web no tiene mucho tráfico, puede ejecutar el servidor de bases de datos en su mismo servidor web. Muchos servidores de bases de datos se ejecutan en Windows.

PHP incluye las extensiones mysqli y pdo_mysql.

Véase» https://dev.mysql.com/downloads/windows/



Instalación manual de PHP en Windows

Elección del servidor web

IIS

IIS está integrado en Windows. En Windows Server, use Server Manager para añadir el rol de IIS. Asegúrese de incluir CGI Role Feature. En Windows Desktop, use Añadir/Eliminar Programas del Panel de Control para añadir IIS. La documentación de Microsoft tiene» instrucciones detallas. Para aplicaciones web de escritorio y desarrollo web, también se puede usar IIS/Express o PHP Desktop.

Ejemplo #1 Linea de órdenes para configurar IIS y PHP


@echo off

REM Descargar el fichero .ZIP o la compilación de PHP desde http://windows.php.net/downloads/
REM
REM Ruta al directorio donde se ha descomprimido el fichero .ZIP de PHP
set phpdir=c:\php


REM Limpiar los manejadores actuales de PHP
%windir%\system32\inetsrv\appcmd clear config /section:system.webServer/fastCGI
REM El siguiente comando generará un mensaje de error si PHP no está instalado. Esto puede ser ignorado.
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /-[name='PHP_via_FastCGI']

REM Instalar el manejador de PHP
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI /+[fullPath='%phppath%\php-cgi.exe']
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /+[name='PHP_via_FastCGI',path='*.php',verb='*',modules='FastCgiModule',scriptProcessor='%phppath%\php-cgi.exe',resourceType='Unspecified']
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /accessPolicy:Read,Script

REM Configurar las variables de FastCGI
%windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"

Apache

Existen varias compilaciones de Apache2 para Windows. Se recomiendan las compilaciones Apache de ApacheLounge, aunque otras opciones pueden ser XAMPP, WampServer y BitNami, las cuales proporcionan herramientas de instalación automática. Se puede utilizar mod_php o mod_fastcgi para cargar PHP en Apache. Si se emplea mod_php, se DEBE utilizar una compilación TS de Apache construida con la misma versión de Visual C y la misma CPU (x86 o x64).

Elegir una compilación

Descargue las versiones de producción de PHP desde» http://windows.php.net/download/. Todas las compilaciones están optimizadas (PGO), y las versiones de QA y GA se prueban exhaustivamente.

Existen 4 tipos de compilación de PHP:

  • Thread-Safe(TS) - usada para servidores web monoproceso, como Apache con mod_php

  • Non-Thread-Safe(NTS) - usada para IIS y otros servidores web FastCGI (Apache con mod_fastcgi) y la recomendad para scripts de línea de comandos

  • x86 - para sistemas de 32-bits.

  • x64 - para sistemas de 64 bits.



Compilando desde código fuente

Este capítulo enseña cómo compilar PHP a partir del código fuente en Windows, utilizando las herramientas de Microsoft. Para compilar PHP con cygwin, consulte la instalación de unix.Instalación sobre sistemas Unix.

Veáse la documentación Wiki en:» https://wiki.php.net/internals/windows/stepbystepbuild



Línea de comandos PHP en Microsoft Windows

Esta sección contiene notas y sugerencias específicas para conseguir ejecutar PHP en la línea de comandos para Windows.

Nota:

Se debe leer primero elmanual de instalación PHP en Windows

Conseguir ejecutar PHP desde la línea de comandos sin hacer ningún cambio a Windows.

C:\php\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3

Pero hay algunos pasos sencillos que puede seguir para hacer esto simple. Algunas de estas medidas ya se deberían haber tomado, pero se repiten aquí para ser capaz de proporcionar una completa secuencia paso a paso.

    Nota:

    TantoPATHcomoPATHEXTson variables de sistema preexistentes importantes en Windows, por lo que se ha de asegurarse de no sobrescribir dichas variables, solamente agregarle algo.

  • Añada la ubicación del ejecutable de PHP (php.exe,php-win.exeophp-cli.exedependiendo de su versión de PHP y las preferencias de presentación) a la variable de entornoPATH. Lea más acerca de cómo añadir el directorio de PHPPATHen laentrada correspondiente de preguntas frecuentes.

  • Añada la extensión.PHPde la variable de entornoPATHEXT. Esto se puede hacer al mismo tiempo, con la modificación de la variable de entornoPATH. Siga los mismos pasos como se describe en lasPreguntas frecuentespero habría que modificar la variable de entornoPATHEXTen lugar de la variable de entornoPATH.

    Nota:

    La posición en que se coloca el.PHPdetermina qué secuencia de comandos o programa se ejecuta cuando hay nombre de archivos coincidentes. Por ejemplo, colocar.PHPantes de.BAThará que el script se ejecute, en lugar de el archivo por lotes, si hay un fichero por lotes con el mismo nombre.

  • Asociar la extensión.PHPcon un tipo de fichero. Esta se hace ejecutando el siguiente comando:

       assoc .php=phpfile
       

  • Asociar el tipo de ficherophpfilecon el adecuado ejecutable PHP. Esto se hace ejecutando el siguiente comando:

       ftype phpfile="C:\PHP5\php.exe" -f "%1" -- %~2
       

Si sigue estos pasos permitirá ejecutar scripts PHP desde cualquier directorio sin necesidad de escribir el ejecutable PHP o la extensión.PHPy todos los parámetros, será enviada a el script para el procesamiento.

En el ejemplo a continuación se detallan algunos de los cambios de registro que se puede hacer manualmente.

Ejemplo #1 Registro de cambios

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php]
@="phpfile"
"Content Type"="application/php"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile]
@="PHP Script"
"EditFlags"=dword:00000000
"BrowserFlags"=dword:00000008
"AlwaysShowExt"=""

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon]
@="C:\\php\\php-win.exe,0"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell]
@="Open"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open]
@="&Open"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command]
@="\"C:\\php\\php.exe\" -f \"%1\" -- %~2"

Con estos cambios el mismo comando se puede escribir como:

"C:\PHP Scripts\script" -arg1 -arg2 -arg3
O, si la ruta de acceso"C:\PHP Scripts"está en el variable de entornoPATH:
script -arg1 -arg2 -arg3

Nota:

Hay un pequeño problema si tiene intención de utilizar esta técnica y usar scripts PHP como filtro de línea de comandos, como el ejemplo a continuación:

dir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3
o
dir | script -arg1 -arg2 -arg3
Es posible que el script simplemente se cuelga y no salga nada. Para hacer esto operacional, es necesario hacer otro cambio en el registro.
Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
"InheritConsoleHandles"=dword:00000001
Información adicional sobre este tema se pueden encontrar en el» Artículo de la base de conocimientos de Microsoft: 321788. A partir de Windows 10, este ajuste parece haber sido invertido, haciendo que la instalación predeterminada de Windows 10 admita manejadores de consola heredados automáticamente. Esta»  entrada del foro de Microsoftproporciona la explicación.



Apache 2.x en Microsoft Windows

Esta sección contiene notas y sugerencias específicas de Apache 2.x instaladas con PHP en sistemas Microsoft Windows.

Nota:

Se debe leer primero elmanual de instalación PHP en Windows

Se recomienda consultar la» Documentación de Apachepara obtener un conocimiento básico del servidor Apache 2.x. También considere leer las» notas específicas para Windowspara Apache 2.x antes de seguir leyendo.

Descargue la versión más reciente de» Apache 2.xy una versión adecuada de PHP. Siga los pasos delmanual de instalacióny regrese para continuar con la integración de PHP y Apache.

Hay tres formas de configurar PHP para que funcione con Apache 2.x en Windows. PHP se puede ejecutar como controlador, como CGI o bajo FastCGI

Nota:Recuerde que cuando agrega rutas como valores en los archivos de configuración de Apache en Windows, todas las barras invertidas tal comoc:\directory\file.extdeberían ser convertidas en barras comunes:c:/directory/file.ext. Una barra común al final será necesaria para directorios.

Instalación como un controlador de Apache

Para cargar el módulo PHP en Apache 2.x las siguientes líneas en el fichero de configuraciónhttpd.confde Apache deben ser añadidas:

Ejemplo #1 PHP y Apache 2.x como controlador

#
LoadModule php8_module "c:/php/php8apache2_4.dll"
AddHandler application/x-httpd-php .php
# configure the path to php.ini
PHPIniDir "C:/php"

Nota:Recuerde, la ruta real de PHP debe sustituirse porC:/php/en los ejemplos anteriores. Asegúrese que el fichero al que hace referencia en la directiva LoadModule está en la ubicación especificada, y utilizephp7apache2_4.dllpara PHP 7, ophp8apache2_4.dllpara PHP 8.

The above configuration will enable PHP handling of any file that has a .php extension, even if there are other file extensions. For example, a file namedexample.php.txtwill be executed by the PHP handler. To ensure that only files thatend in.phpare executed, use the following configuration instead: La configuración anterior permitirá el manejo de PHP de cualquier fichero que contenga la extensión .php, incluso si hay otras extensiones de fichero. Por ejemplo, el fichero llamadoexample.php.txtserá ejecutado por el controlador PHP. Para garantizar que solo se ejecuten los ficheros queterminen en.php, utilice la siguiente configuración:

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

Ejecución de PHP como CGI

Se recomienda consultar la» documentación de Apache CGIpara una comprensión más completa de la ejecución de CGI en Apache.

Para ejecutar PHP como CGI, deberá colocar los ficheros php-cgi en un directorio designado como directorio CGI utilizando la directiva ScriptAlias.

Será necesario colocar una línea#!en los ficheros PHP, que apunte a la ubicación del binario PHP:

Ejemplo #2 PHP y Apache 2.x como CGI

#!C:/php/php.exe
<?php
  phpinfo();
?>

Advertencia

Al usar el modo CGI, su servidor esta expuesto a diferentes ataques. Por favor, leer la secciónSeguridad con CGIpara aprender cómo defenderse de estos ataques.

Ejecutando PHP bajo FastCGI

Ejecutar PHP bajo FastCGI tiene una serie de ventajas con respecto a ejecutarlo bajo CGI. Configurarlo de esta manera es bastante sencillo:

Descarguemod_fcgiddesde» https://www.apachelounge.com. Los binarios de Win32 están disponibles para descargar desde ese sitio. Instale el módulo de acuerdo con las instrucciones que lo acompañarán.

Configure su servidor web como se muestra a continuación, teniendo cuidado de ajustar cualquier ruta que reflejen la forma en que ha instalado las cosas en su sistema particular:

Ejemplo #3 Configurar Apache para ejecutar PHP como FastCGI

LoadModule fcgid_module modules/mod_fcgid.so
# ¿Dónde está el fichero php.ini?
FcgidInitialEnv PHPRC        "c:/php"
AddHandler fcgid-script .php
FcgidWrapper "c:/php/php-cgi.exe" .php
Los archivos con una extensión .php ahora serán ejecutados por el contenedor PHP FastCGI.



Resolución de problemas de PHP en Windows

Comprobar los permisos del directorio temporal

  1. Clic derecho en el directorio temporal con el Explorador de archivos para mostrar los permisos.

  2. Para IIS, compruebe que el usuario IIS_User posee el permiso MODIFY. Se puede saber cuál es el directorio temporal a través de la configuración o información de php.




Instalación en las plataformas de Nube Informática

Tabla de contenidos

PHP instalará en la nube. A la nube de PHP!


Microsoft Azure

PHP instalará el Azure cloud platform.

Ver acerca de Azure SDK para PHP.



Amazon EC2

PHP instalará el» EC2 cloud platform.

Ver acerca de» AWS SDK for PHP.




Manejador de Procesos FastCGI (FPM)

Tabla de contenidos

FPM (FastCGI Process Manager) es una implementación alternativa al PHP FastCGI con algunas características adicionales (la mayoría) útiles para sitios web con mucho tráfico.

Estas características incluyen:

  • Manejo avanzado para detener/arrancar procesos de forma fácil;

  • Posibilidad de iniciar hilos de procesos con diferentes uid/gid/chroot/environment, escuchar en diferentes puertos y usar distintos php.ini (remplazando); safe_mode

  • Registro stdout y stderr;

  • Reinicio de emergencia en caso de destrucción accidental del caché opcode;

  • Soporte acelerado de subidas;

  • "slowlog" - scripts de registro de procesos (no sólo sus nombres, sin sus backtraces también, usando ptrace y similares para leer procesos execute_data remotos) que son inusualmente lentos;

  • fastcgi_finish_request()- Función especial para detener y descargar todos los datos mientras continua haciendo algún proceso más largo (conversión de vídeos, procesamiento de estadísticas, etc.);

  • Creación dinámico/estático de hilos;

  • Información básica del status SAPI (similar al mod_status de Apache);

  • Basado en archivos de configuración php.ini


Instalación

Compilación desde el código fuente

Para habilitar FPM en la construcción de PHP, debe añadirse--enable-fpma la línea de configuración.

Hay otras opciones de configuración específicas de FPM (todas ellas optativas):

  • --with-fpm-user- Establecer el usuario de FPM (por omisión: nobody).

  • --with-fpm-group- Establecer el grupo de FPM (por omisión: nobody).

  • --with-fpm-systemd- Activar la integración del sistema (por omisión: no).

  • --with-fpm-acl- Utilizar las listas de control de acceso de POSIX (por omisión: no). Desde 5.6.5



Configuración

FPM usa la sintaxis dephp.inipara su fichero de configuración -php-fpm.conf, y agrupa ficheros de configuración.

Lista de directivas globales dephp-fpm.conf

pidstring

Ruta al fichero PID. Valor por defecto: none.

error_logstring

Ruta al fichero de registro de errores. Valor por defecto:#INSTALL_PREFIX#/log/php-fpm.log. Si se establece a "syslog", los registros son enviados a syslogd en lugar de escribir en un archivo local.

log_levelstring

Nivel de registro de errores. Posibles valores: alert, error, warning, notice, debug. Valor por defecto: notice.

log_limitint

Límite de registro para las líneas registradas que permite registrar mensajes de más de 1024 caracteres sin envolver. Valor por defecto: 1024. Disponible a partir de PHP 7.3.0.

log_bufferingbool

Registro experimental sin almacenamiento adicional en el búfer. Valor por defecto: sí. Disponible a partir de PHP 7.3.0.

syslog.facilitystring

Usado para especificar qué tipo de programa está recibiendo los mensajes de registro. Valor por defecto: daemon.

syslog.identstring

Anteponer a cada mensaje. Si hay varias instancias FPM ejecutándose en el mismo servidor, puede cambiar el valor por defecto que debe adaptarse a sus necesidades. Valor por defecto: php-fpm.

emergency_restart_thresholdint

Si este número de procesos termina con SIGSEGV o SIGBUS dentro del intervalo de tiempo establecido poremergency_restart_intervalentonces FPM se reiniciará. Un valor de 0 corresponde a 'Off'. Valor por defecto: 0 (Off).

emergency_restart_intervalmixed

Intervalo de tiempo usado poremergency_restart_intervalpara determinar cuando un reinicio agraciado será realizado. Esto puede ser útil trabajar sobre corrupciones accidentales in en acelerador de memoria compartida. Unidades disponibles:: s(segundos), m(inutos), h(oras), o d(ías). Unidad por defecto: segundos. Valor por defecto: 0 (Off).

process_control_timeoutmixed

Límite de tiempo que un hilo de proceso espera por una señal maestra. Unidades disponibles: s(egundos), m(inutos), h(oras), o d(ías) Unidad por defecto: segundos. Valor por defecto: 0.

process.maxint

El número máximo de procesos FPM creará. Esto ha sido diseñado para controlar el número global de procesos cuando se utiliza PM dinámico dentro de muchos pools. Utilícelo con precaución. Valor por defecto: 0.

process.priorityint

Especifique la prioridad nice(2) que se aplicará al proceso maestro (sólo si se establece). El valor puede variar entre -19 (prioridad más alta) hasta 20 (prioridad más baja). Valor por defecto: no establecido.

daemonizeboolean

Envía a FPM al background. Establezca a 'no' para mantener FPM en foreground para depuración. Valor por defecto: yes.

rlimit_filesint

Establece el descriptor rlimit de archivos abiertos para el proceso maestro. Valor predeterminado: Establece el descriptor rlimit de archivos abiertos para el proceso maestro.

rlimit_coreint

Establece el tamaño máximo del núcleo rlimit para el proceso maestro. Valor por defecto: 0.

events.mechanismstring

Especifica el mecanismo de eventos que FPM utilizará. Los siguientes están disponibles: select, pool, epoll, kqueue (*BSD), port (Solaris). Valor por defecto: no establecido (auto-detección).

systemd_intervalint

Cuando FPM es compilado con integración con systemd, especifique el intervalo, en segundos, entre notificaciones de reporte de salud a systemd. Coloque a 0 para deshabilitar. Valor por defecto: 10.

Lista de directivas de grupo

Con FPM usted puede correr varios grupos de procesos con diferentes ajustes. Estos son los parámetros que pueden ser ajustados por grupo.

listenstring

La dirección sobre la cual desea aceptar peticiones FastCGI. Las sintaxis válidas son: 'ip.add.re.ss:port', 'port', '/path/to/unix/socket'. Esta opción es obligatoria por cada grupo.

listen.backlogint

Establece listen(2) backlog. Un valor de '-1' significa ilimitado. Valor por defecto: -1.

listen.allowed_clientsstring

Lista de direcciones ipv4 de clientes FastCGI que tienen permiso para conectarse. El equivalente a la variable de entorno FCGI_WEB_SERVER_ADDRS en el PHP FastCGI (5.2.2+) original. Tiene sentido solamente con un socket tcp escuchando. Cada dirección debe ser separada por coma. Si este valor es dejado en blanco, las conexiones serán aceptas desde cualquier dirección ip. Valor por defecto: any.

listen.ownerstring

Establece permisos para sockets unix, si uno es usado. En Linux, los permisos de lectura/escritura deben ser puestos a fin de permitir conexiones desde un servidor web. Muchos sistemas derivados de BSD permiten conexiones sin considerar los permisos. Valor por defecto: usuario y grupo son establecidos según el usuario ejecutor, permisos puestos a 0660.

listen.groupstring

Verlisten.owner.

listen.modestring

Verlisten.owner.

listen.acl_usersstring

Cuando las lsitas de control de acceso POSIX están soportadas, usted puede configurarlas usando esta opción. Cuando se establece,listen.ownerylisten.groupson ignoradas. El valor es una lista de nombres de usuario separado por comas. Desde PHP 5.6.5.

listen.acl_groupsstring

Verlisten.acl_users. El valor es una lista de nombres de grupo separado por comas. Desde PHP 5.6.5.

userstring

Usuario Unix de procesos FPM. Esta opción es obligatoria.

groupstring

Grupo Unix group of FPM processes. Si no es establecido, el grupo del usuario por defecto será usado.

pmstring

Seleccione cómo el manejador de procesos controlará el número de hilos de procesos. Valores posibles:static,ondemand,dynamic. Esta opción es obligatoria.

static- el número de hilos de proceso es fijo (pm.max_children).

ondemand- el proceso se lanza en demanda (cuando se solicita, al contrario que dynamic, dondepm.start_serversson iniciados cuando el servicio está iniciado.

dynamic- el número de hilos de proceso será basado dinámicamente basado en las siguientes directivas:pm.max_children,pm.start_servers,pm.min_spare_servers,pm.max_spare_servers.

pm.max_childrenint

El número de hilos de procesos a ser creados cuandopmes puesto astaticy el máximo número de hilos de proceso a ser creados cuandopmes puesto adynamic. Esta opción es obligatoria.

Esta opción establece el límite sobre el número de peticiones simultaneas que serán servidas. Equivale a la directiva ApacheMaxClients con mpm_prefork y a la variable de entornoPHP_FCGI_CHILDRENdel PHP FastCGI original.

pm.start_serversint

Número de hilos de procesos creados al inicio. Usado solamente cuandopmes puesto adynamic. Valor por defecto: min_spare_servers + (max_spare_servers - min_spare_servers) / 2.

pm.min_spare_serversint

El número mínimo deseado de procesos libres en el servidor. Usado sólo cuandopmes puesto adynamic. También obligatorio en este caso.

pm.max_spare_serversint

El número máximo deseado de procesos libres en el servidor. usado sólo cuandopmes puesto adynamic. También obligatorio en este caso.

pm.process_idle_timeoutmixed

El número de segundos después de los cuales se matará un proceso inactivo. Usado sólo cuandopmestá establecido comoondemand. Unidades disponibles: s(segundos)(predeterminado), m(inutos), h(horas), o d(ías). Valor por defecto: 10s.

pm.max_requestsint

El número de pedidos que cada hilo de proceso debe ejecutar antes de reaparecer. Esto puede ser útil para evitar las fugas de memoria en librerías de terceros. para el procesamiento de solicitudes sin límites especifique '0'. Equivale aPHP_FCGI_MAX_REQUESTS. Valor por defecto: 0.

pm.status_pathstring

La dirección URI para verla página de status FPM. Este valor debe comenzar con una barra inclinada (/). Si no se establece este valor, no se reconocerá ninguna URI como página de estado. Valor por defecto: ninguno. . Valor por defecto: none.

ping.pathstring

La dirección URI del ping para llamar a la página de monitor del FPM. Si este valor no es establecido, ninguna dirección URI será reconocida como página del ping. Esto debería ser usado para probar desde el exterior que el FPM está funcionando y respondiendo. Por favor, note que este valor debe empezar con un slash (/).

ping.responsestring

Esta directiva puede ser usada para personalizar las peticiones de respuestas a ping. La respuesta es formateada como text/plain con un código de respuesta 200. Valor por defecto: pong.

process.priorityint

Especifique la prioridad nice(2) que se aplicará al proceso maestro (sólo si se establece). El valor puede variar entre -19 (prioridad más alta) hasta 20 (prioridad más baja). Valor por defecto: no establecido.

process.dumpablebool

Establece el indicador de proceso descargable (PR_SET_DUMPABLE prctl) incluso si el usuario o grupo del proceso o grupo es diferente al usuario del proceso maestro. Permite crear el proceso core dump y ptrace el proceso para el usuario del pool. Valor por defecto: no. Desde de PHP 7.0.29, 7.1.17 y 7.2.5.

prefixstring

Establece un prefijo para la ruta de evaluación

request_terminate_timeoutmixed

El tiempo de espera para servir una simple petición luego que el proceso worker sea eliminado. Esta opción debe ser usada cuando la opción 'max_execution_time' no detenga la ejecuciuón del script por cualquier razón. Un valor de '0' corresponde a 'Off'. Unidades disponibles: s(egundos)(por defecto), m(inutos), h(horas), or d(ías). Default value: 0.

request_slowlog_timeoutmixed

El tiempo de espera para servir una simple petición después de que un backtrace PHP sea volcado al fichero 'slowlog'. Un valor de '0' corresponde a 'Off'. Unidades disponibles: s(egundos)(por defecto), m(inutos), h(oras), or d(ías). Valor por defecto: 0.

slowlogstring

El fichero de registro para peticiones lentas. Valor por defecto:#INSTALL_PREFIX#/log/php-fpm.log.slow.

rlimit_filesint

Establece el fichero descriptor rlimit. Valor por defecto: definido por el sistema.

rlimit_coreint

Establece el tamaño máximo del rlimit. Valores posibles: 'unlimited' o un entero mayor o igualo a 0. Valor por defecto: definido por el sistema.

chrootstring

Establece el Chroot (enjaulado) a este directorio al inicio. Este valor debe ser definido como una ruta absoluta. Cuando este valor no es establecido, el chroot no es usado.

chdirstring

Establece el Chdir a este directorio al inicio. Este valor debe ser establecido como una ruta absoluta. Valor por defecto: directorio actual o / cuando está en chroot (enjaulado).

catch_workers_outputboolean

Redirige los worker stdout y stderr en el fichero de registro principal. Sí no es establecido, stdout y stderr serán redirigidos a /dev/null de acuerdo a las especificaciones FastCGI. Valor por defecto: no.

decorate_workers_outputbool

Habilitar la decoración de salida para la salida de loscatch_workers_outputsi está activado. Valor por defecto: sí. Disponible a partir de PHP 7.3.0.

clear_envboolean

Entorno limpio in workers FPM. Evita que variables de entorno arbitrarias lleguen a los procesos FPM mediante la limpieza del entorno en los workers antes de que se añadan las variables env a las pools correspondientes a esta configuración. Desde PHP 5.4.27, 5.5.11, y 5.6.0. Valor por defecto: Yes.

security.limit_extensionsstring

Limita las extensiones del script principal que FPM procesará. Esto puede evitar errores de configuración del lado del servidor. Usted debería limitar su FPM a procesar unicamente extensiones .php para evitar que usuarios malintencionados usen diferentes extensiones para ejecutar código PHP. Valor por defecto: .php .phar

access.logstring

Archivo de registro de acceso. Valor por defecto: no establecido

access.formatstring

Formato del archivo de registro de acceso. Valor por defecto: "%R - %u %t \"%m %r\" %s"

Opciones válidas
PlaceholderDescripción
%C%CPU
%dduration µs
%efastcgi env
%fscript
%lcontent length
%mmethod
%Mmemory
%npool name
%oheader output
%pPID
%qquery string
%Qthe glue between %q and %r
%rrequest URI
%Rremote IP address
%sstatus
%Ttime
%ttime
%uremote user

Es posible pasar las variables de entorno adicionales y actualizar los ajustes PHP de ciertos grupos. Para ello, se necesita agregar las siguientes opciones al fichero de configuración.

Ejemplo #1 Pasando variables de entorno y ajustando las configuraciones de PHP por grupos

env[HOSTNAME] = $HOSTNAME
env[PATH] = /usr/local/bin:/usr/bin:/bin
env[TMP] = /tmp
env[TMPDIR] = /tmp
env[TEMP] = /tmp

php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
php_flag[display_errors] = off
php_admin_value[error_log] = /var/log/fpm-php.www.log
php_admin_flag[log_errors] = on
php_admin_value[memory_limit] = 32M
Los ajustes PHP pasados conphp_valueophp_flagserán sobre-escritos a sus valores previos. Por favor note que definiendodisable_functionsodisable_classesno sobre-escribirá los valores de definiciones anterioresphp.ini, pero añadirán nuevos en cambio.

Ajustes definidos conphp_admin_valueandphp_admin_flagcannot be anulados conini_set().

Como 5.3.3, establecer los ajustes PHP es también posible como servidor web.

Ejemplo #2 Establecer ajustes PHP en nginx.conf

set $php_value "pcre.backtrack_limit=424242";
set $php_value "$php_value \n pcre.recursion_limit=99999";
fastcgi_param  PHP_VALUE $php_value;

fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";
Precaución

Dado a que estos valores se pasan a php-fpm como cabeceras fastcgi, php-fpm no debe estar vinculado a una dirección accesible para todo el mundo. De lo contrario, cualquiera podría alterar las opciones de configuración de PHP. Ver tambiénlisten.allowed_clients.

Nota:Los pools no son un mecanismo de seguridad, porque no proporcionan una separación total; por ejemplo, todos los pools utilizarían una única instancia de OPcache.




Instalación de extensiones PECL

Tabla de contenidos


Introducción a las Instalaciones en PECL

» PECLes un repositorio de extensiones de PHP disponible mediante el sistema de paquetes» PEAR. Esta sección del manual tiene por objetivo ilustrar cómo obtener e instalar extensiones PECL.

Estas instrucciones asumen que la ruta al fuente de su distribución de PHP es/your/phpsrcdir/, y queextnamees el nombre de la extensión PECL. Ajuste a sus valores. Estas instrucciones, además, asumen conocimientos del» comando pear. La información del manual de PEAR para el comandopeartambién es aplicable al comandopecl.

Para poder usarse, una extensión compartida se debe construir, instalar, y cargar. Los métodos descritos abajo le proporcionan varias instrucciones para construir e instalar extensiones, pero no se cargarán automáticamente. Éstas se pueden cargar añadiendo una directivaextension. al ficherophp.ini, o bien mediante el uso de la funcióndl().

Al construir un módulo PHP, es importante contar con las versiones correctas de las herramientas requeridas (autoconf, automake, libtool, etc.). Para conocer los detalles de las herramientas requeridas y sus versiones, revise las» Instrucciones de Git Anónimo.



Descarga de extensiones PECL

Existen varias opciones para descargar extensiones PECL, a saber:

  • El comandopecl install extnamedescarga el código de la extensión automáticamente, de modo que en este caso no se hace necesario realizar una descarga por separado.
  • » https://pecl.php.net/La página web de PECL contiene información sobre las diferentes extensiones que ofrece el Equipo de Desarrollo de PHP. La información disponible aquí incluye: ChangeLog, notas de la versión, requisitos, y otros detalles similares.
  • pecl download extnamePuede descargar e instalar las extensiones PECL listadas en el sitio web de PECL usando el» comando pecl. También se podrán especificar versiones concretas.
  • SVNLa mayor parte de las extensiones PECL también están alojadas enSVN. Puede consultar la interfaz web en» https://svn.php.net/pecl/. Para descargar directamente delSVN, debe usar la siguiente secuencia de comandos:


    $ svn checkout http://svn.php.net/repository/pecl/extname/trunk extname

  • Descargas para WindowsEl proyecto PHP compila y ofrece DLL de Windows para la mayoría de extensiones PECL en la página del paquete respectivo.


Instalación una extensión de PHP en Windows

Dispone de dos formas para cargar extensiones PHP en Windows: o bien compilándolas en PHP, o bien cargando su DLL. El método recomendado y más sencillo es cargar una extensión pre-compilada.

Para cargar una extensión, debe estar disponible como fichero ".dll" en su sistema. Todas las extensiones son compiladas por el Grupo PHP automática y periódicamente (revise la siguiente sección para realizar descargas).

Para compilar una extensión en PHP, por favor, acceda a la documentación deconstrucción de la fuente.

Para compilar una extensión independiente (o lo que es lo mismo, un fichero DLL), por favor, revise la documentación deconstrucción de la fuente. Si el fichero DLL no está disponible ni en su distribución de PHP ni en PECL, deberá compilarla antes de poder comenzar a usarla.

¿Dónde encontrar una extensión?

Las extensiones de PHP generalmente se llaman "php_*.dll" (donde el asterisco representa el nombre de la extensión) y se localizan bajo la carpeta "PHP\ext".

PHP se distribuye con las extensiones más útiles para la mayoría de desarrolladores. Se les llama extensiones del "núcleo".

En cualquier caso, si necesita una funcionalidad que no proporciona ninguna de las extensiones del núcleo, podrá buscarla en PECL. La Biblioteca de la Comunidad de Extensiones de PHP (PECL) es un repositorio de extensiones PHP, que proporciona un directorio de todas las extensiones conocidas, y aloja utilidades para descargar y desarrollar extensiones de PHP.

Si usted ha desarrollado una extensión para su propio uso, quizá quiera considerar alojarla en PECL, de forma que otros desarrolladores con las mismas necesidades puedan verse beneficiados de su tiempo. Una de las ventajas es que tendrá la oportunidad de recibir colaboración, (ojalá) agradecimientos, informes de errores, e incluso parches/correcciones. Antes de enviar su extensión para ser alojada en PECL, por favor, lea» el envío a PECL.

¿Qué extensión descargar?

A menudo, encontrará varias versiones de cada DLL:

  • Números de versión diferentes (al menos los dos primeros números deben coincidir)
  • Diferentes ajustes de seguridad en hilos
  • Diferentes arquitecturas de procesadores (x86, x64, ...)
  • Diferentes ajustes de depuración
  • etc.

Debe tener en cuenta que los ajustes de su extensión deben coincidir con la configuración del ejecutable de PHP que está utilizando. El siguiente script de PHP le dirátodosobre sus ajustes de PHP:

Ejemplo #1 llamada aphpinfo()

<?php
phpinfo
();
?>

O ejecute desde la línea de comandos:

drive:\\path\to\php\executable\php.exe -i

Cargando una extensión

La forma más común de cargar una extensión PHP consiste en incluirla en el fichero de configuraciónphp.ini. Por favor, tenga en cuenta que ya hay muchas extensiones presentes en el ficherophp.iniy que sólo es necesario eliminar el punto y coma para activarlas.

Observe que en versiones de PHP 7.2.0 y superiores, se podría utilizar el nombre de extensión en lugar del nombre de fichero de la extensión. Ya que esto es independiente del SO y más sencillo, especialmente para recién llegados, se convierte en la forma recomendada de especificar estensiones a cargar. El soporte para nombres de ficheros permanece por compatibilidad con versiones anteriores.

;extension=php_extname.dll
extension=php_extname.dll
; On PHP version 7.2 and up, prefer :
extension=extname
zend_extension=another_extension

Sin embargo, algunos servidores web puede resultar confusos, dado que no utilizan elphp.iniubicado junto al ejecutable de PHP. Para averiguar dónde se localiza elphp.inien uso, consulte su ruta usandophpinfo():

Configuration File (php.ini) Path  C:\WINDOWS
Loaded Configuration File   C:\Program Files\PHP\5.2\php.ini

Tras activar una extensión, guarde el ficherophp.ini, reinicie el servidor web y vuelva a comprobarphpinfo(). La nueva extensión debe ahora tener su propia sección.

Resolviendo problemas

Si la extensión no aparece enphpinfo(), compruebe los registro de errores para conocer qué provoca el problema.

Si está utilizando PHP desde la línea de comandos (CLI), podrá leer directamente en pantalla el error en la carga de la extensión.

Si está usando PHP en un servidor web, la localización y formato de los registros vería en función de su software. Por favor, lea la documentación de su servidor web para localizar los registros, dado que esto no lo gestiona el propio ejecutable de PHP.

Los problemas más comunes son la ubicación del fichero DLL, el valor de "extension_dir" enphp.ini, y desajustes de configuración en tiempo de compilación.

Si el problema reside en desajustes de configuración en tiempo de compilación, seguramente se deba a que no se ha descargado el fichero DLL correcto. Pruebe a descargar de nuevo la extensión con los ajustes correctos. De nuevo,phpinfo()puede resultar de gran ayuda.



Compilando extensiones PECL compartidas con el comando pecl

PECL facilita la creación de extensiones PHP compartidas. Usando el» comando pecl, haga lo siguiente:


$ pecl install extname

Esto descargará el código fuente deextname, lo compilará, e instalaráextname.soen suextension_dir. Ahora se puede cargarextname.somediantephp.ini

Por omisión, el comandopeclno instalará paquetes marcados en los estadosalphaobeta. Si no hay paquetes disponibles en estadostable, podrá instalar un paquete en estadobetautilizando el siguiente comando:


$ pecl install extname-beta

Del mismo modo, podrá también instalar una versión en concreto usando esta variante:


$ pecl install extname-0.1

Nota:

Tras activar la extensión enphp.ini, será necesario reiniciar el servidor web para hacer efectivos los cambios.



Compilando extensiones PEC compartidas con phpize

A menudo no es posible utilizar el instaladorpecl. Esto se puede deber a que se encuentra tras un cortafuegos, o a que la extensión que trata de instalar no está disponible como paquete compatible con PECL, como por ejemplo extensiones no liberadas desde el SVN. Si necesita construir una extensión de este tipo, puede llevar a cabo esta tarea manualmente utilizando las herramientas de construcción de bajo nivel.

El comandophpizese utiliza para preparar el entorno de compilación de la extensión de PHP. En el siguiente ejemplo, el fuente de una extensión se ubica en un directorio llamadoextname:

$ cd extname
$ phpize
$ ./configure
$ make
# make install

En caso de que la instalación sea correcta, se crearáextname.soy se salvará en eldirectorio de extensionesde PHP. Quizá necesite ajustar el ficherophp.iniy añadir una líneaextension=extname.soantes de poder usar la extensión.

Si el sistema no contiene el comandophpize, y se están utilizando paquetes pre-compilados (como RPM), asegúrese de instalar también la versión de desarrollo apropiada del paquete PHP, dado que a menudo incluyen el comandophpizecon los ficheros de cabeceras necesarios para construir PHP y sus extensiones.

Ejecutephpize --helppara mostrar información de uso adicional.



php-config

php-config es una utilidad de consola que permite obtener información sobre la configuración de la instalación de PHP.

A la hora de compilar extensiones, si se tuvieran varias versiones de PHP instaladas, se podrá especificar sobre cuál se va a construir usando el modificador--with-php-configdurante la configuración, donde especificaremos la ruta a su respecto script php-config.

En cualquier momento podrá consutlarse la lista de opciones de la utilidad php-config ejecutando php-config con el modificador-h:

Usage: /usr/local/bin/php-config [OPTION]
Options:
  --prefix            [...]
  --includes          [...]
  --ldflags           [...]
  --libs              [...]
  --extension-dir     [...]
  --include-dir       [...]
  --php-binary        [...]
  --php-sapis         [...]
  --configure-options [...]
  --version           [...]
  --vernum            [...]

Opciones de línea de comandos
OpciónDescripción
--prefixPrefijo del directorio donde PHP está instalado, p.ej. /usr/local
--includesLista de opciones -I con todos los ficheros incluídos
--ldflagsBanderas LD con las que se ha compilado PHP
--libsBibliotecas extras con las que se ha compilado PHP
--extension-dirDirectorio en el que se buscan por omisión las extensiones
--include-dirPrefijo de directorio donde se buscan por omisión los ficheros de cabeceras
--php-binaryRuta completa al binario de php CLI o CGI
--php-sapisMuestra todos los módulos SAPI disponibles
--configure-optionsOpciones de configuración para recrear la configuración de la instalación actual de PHP
--versionVersión de PHP
--vernumVersión de PHP en forma de entero



Compilando extensiones PECL estáticamente en PHP

Quizá necesite construir una extensión PECL estáticamente en su binario de PHP. Para hacer esto, necesitará ubicar el fuente de la extensión bajo el directorio/su/directorio_fuentes_php/ext/e indicarle al sistema de construcción de PHP que regenere su script de configuración.

$ cd /your/phpsrcdir/ext
$ pecl download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname

Esto generará el siguiente directorio:


/your/phpsrcdir/ext/extname

Desde aquí, fuerce a PHP a regenerar el script de configuración, y entonces construya PHP con normalidad:


$ cd /your/phpsrcdir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install

Nota:Necesitará autoconf 2.13 y automake 1.4+ para ejecutar el script 'buildconf' (es posible que funcionen versiones más recientes de autoconf, pero no están oficialmente soportadas).

Dependiendo de la extensión, utilizará--enable-extnameo--with-extname. Las extensiones que no requieren de bibliotecas externas generalmente utilizan--enable. Para asegurarse, ejecute el siguiente comando después de buildconf:


$ ./configure --help | grep extname




Resolución de problemas

Tabla de contenidos


Lea las Preguntas frecuentes

Algunos problemas son más comunes que otros. Los más comunes se enumeran en lasPreguntas frecuentes de PHPde este manual.



Otros problemas

Si sigue bloqueado, seguramente alguien de la lista de correo de la instalación de PHP podrá ayudarle. Primero, debería consultar el archivo para comprobar si alguien ya ha contestado a otra persona que haya tenido el mismo problema. Los archivos están disponibles desde la página de soporte en» https://www.php.net/support.php. Para subscribirse a la lista de correo de la instalación de PHP (en inglés), envíe un correo vacío a» php-install-subscribe@lists.php.net. La dirección de la lista de correo es» php-install@lists.php.net.

Si quiere obtener ayuda de la lista de correo, por favor trate de ser preciso y dar toda la información necesaria a cerca de su entorno (sistema operativo, versión de PHP, servidor web, si está usando PHP como GCI o como módulo de servidor, etc.), y preferiblemente suficiente código para que otras personas sean capaces de reproducir y probar su problema.



Informar sobre errores (bugs)

Si cree que ha encontrado un error en PHP, por favor informe sobre él. Los desarrolladores de PHP probablemente no estén informados del problema y, a no ser que lo mencione, es muy probable que no sea solucionado. Puede informar sobre errores empleando el sistema de seguimiento de errores en» https://github.com/php/php-src/issues. Por favor, no envíe informes de errores a listas de correos o cartas personales. El sistema de errores también está capacitado para enviar sugerencias y peticiones.

Lea el documento» Cómo informar sobre erroresantes de enviar cualquier informe de errores.




Configuración en tiempo de ejecución

Tabla de contenidos


El fichero de configuración

El fichero de configuración (php.ini) es leído al arrancar PHP. En las versiones en que PHP funciona como módulo de servidor, esto sucede únicamente cuando se inicia el servidor. En las versionesCGIyCLI, esto ocurre en cada ejecución.

El ficherophp.inise busca en las siguientes ubicaciones (en orden):

  • La ubicación específica de módulo SAPI (directivaPHPIniDiren Apache 2, opción de línea de comandos-cen CGI y CLI, parámetrophp_inien NSAPI, variable de entornoPHP_INI_PATHen THTTPD)
  • La variable de entornoPHPRC. Antes de PHP 5.2.0, esta ubicación se comprobaba después de la clave de registro mencionada más abajo.
  • A partir de PHP 5.2.0, se puede establecer la ubicación del ficherophp.inipara diferentes versiones de PHP. Se examinan en orden las siguientes claves de registro:[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z],[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]y[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x], donde 'x', 'y' y 'z' significan la versión mayor, menor, y de edición de PHP. Si existiera un valor paraIniFilePathen cualquiera de estas claves, la primera en ser encontrada se utilizaría como ubicación del ficherophp.ini(solo en Windows).
  • [HKEY_LOCAL_MACHINE\SOFTWARE\PHP], valor deIniFilePath(solo en Windows).
  • El directorio actual de trabajo (excepto CLI)
  • El directorio del servidor web (para módulos SAPI), o el directorio de PHP (excepto en Windows)
  • El directorio de Windows (C:\windowsoC:\winnt) (para Windows), o la opción en tiempo de compilación--with-config-file-path.

Si existiera el ficherophp-SAPI.ini(donde SAPI es la SAPI en uso, por ejemplo,php-cli.iniophp-apache.ini), se usaría éste en lugar dephp.ini. Se puede determinar el nombre de la SAPI usandophp_sapi_name().

Nota:

El servidor web Apache cambia el directorio al raíz al arrancar, haciendo que PHP intente leerphp.inidesde el sistema de ficheros raíz si existiera.

Las variables de entorno se pueden usar enphp.inicomo se muestra abajo.

Ejemplo #1 Variables de entorno dephp.ini

; PHP_MEMORY_LIMIT se toma del entorno
memory_limit = ${PHP_MEMORY_LIMIT}

Las directivas dephp.inimanejadas por extensiones están documentadas en la propia página de cada extensión. Hay unalista de directivas del núcleodisponible en el apéndice. Es posible que no todas las directivas de PHP estén documentadas en el manual: para consultar una lista completa de las directivas disponibles en su versión de PHP, por favor, lea los comentarios del ficherophp.ini. Adicionalmente, puede encontrar útil» el últimophp.inidesde Git.

Ejemplo #2 Ejemplo dephp.ini

; todo texto en una línea tras un punto y coma sin comillas (;) será ignorado
[php] ; los marcadores de sección (textos entre corchetes) también se ignoran
; Los valores de tipo boolean puede establecerse a:
;    true, on, yes
; o  false, off, no, none
register_globals = off
track_errors = yes

; se pueden encerrar los strings entre comillas dobles
include_path = ".:/usr/local/lib/php"

; las barras invertidas reciben el mismo tratamiento que el resto de caracteres
include_path = ".;c:\php\lib"

A partir de PHP 5.1.0, es posible hacer referencia a variables .ini ya existentes desde el propio fichero .ini. Ejemplo:open_basedir = ${open_basedir} ":/new/dir".

Directorios de búsqueda

Es posible configurar PHP para que busque ficheros .ini en un directorio después de leerphp.ini. Esto se puede realizar durante la compilación estableciento la opción--with-config-file-scan-dir. En PHP 5.2.0 y posteriores, el directorio de búsqueda puede ser sobrescrito durante la ejecución estableciendo la vairable de entornoPHP_INI_SCAN_DIR.

Es posible buscar en varios directorios separándolos con el separador de rutas específico de cada plataforma (;en Windows, NetWare y RISC OS;:en las demás plataformas; el valor que PHP emplea está disponible como la constantePATH_SEPARATOR). Si se proporciona aPHP_INI_SCAN_DIRun directorio en blanco, PHP también buscará en el directorio dado durante la compilación mediante--with-config-file-scan-dir.

PHP buscará dentro de cada directorio todos los ficheros que finalicen en.inien orden alfabético. Se puede obtener una lista de los ficheros cargados, y en qué orden, llamando aphp_ini_scanned_files(), o ejecutando PHP con la opción--ini.

Se asumen que PHP está configurado con --with-config-file-scan-dir=/etc/php.d,
y que el separador de rutas es :...

$ php
  PHP cargará todos los ficheros de /etc/php.d/*.ini como ficheros de configuración.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
  PHP cargará todos los ficheros de /usr/local/etc/php.d/*.ini como
  ficheros de configuración.

$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
  PHP cargará todos los ficheros de /etc/php.d/*.ini, y luego de
  /usr/local/etc/php.d/*.ini como ficheros de configuración.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP cargará todos los ficheros de /usr/local/etc/php.d/*.ini, y luego de
  /etc/php.d/*.ini como ficheros de configuración.

Historial de cambios

VersiónDescripción
7.0.0Las almohadillas (#) ya no se reconocen como comentarios.
5.3.0Las almohadillas (#) ya no deberían utilizarse como comentarios, ya que lanzarán una advertencia de obsolescencia si se emplean.
5.2.0La variable de entornoPHP_INI_SCAN_DIRse puede establecer para sobrescribir el directorio de búsqueda mediante el script de configuración.
5.1.0Es posible referirse a variables .ini existentes dentrode ficheros .ini.



Ficheros .user.ini

A partir de PHP 5.3.0 se incluye soporte para ficheros de configuración INI a nivel de directorios. Estos ficherossololos procesa la SAPI CGI/FastCGI. Esta funcionalidad deja obsoleta la extensión PECL htscanner. Si está usando Apache, use los ficheros.htaccesspara lograr el mismo efecto.

Además del ficherophp.iniprincipal, PHP explora cada directorio en busca de ficheros INI, empezando por el directorio del fichero PHP solicitado, y continuando hasta el directorio raíz de documentos (tal y como esté establecido en$_SERVER['DOCUMENT_ROOT']). En el caso de que el fichero PHP se encuentre fuera del directorio raíz de documentos, sólo se explorará su directorio.

En los ficheros INI estilo .user.ini sólo se reconocerán las configuraciones INI que tengan los modosPHP_INI_PERDIRyPHP_INI_USER.

Las dos nuevas directivas INI,user_ini.filenameyuser_ini.cache_ttlcontrolan el uso de los ficheros INI de usuarios.

user_ini.filenameestablece el nombre del fichero que PHP buscará en cada directorio; si se establece un string vacío, PHP no realizará ninguna búsqueda. El nombre por omisión es.user.ini.

user_ini.cache_ttlcontrola con qué frecuencia se releen los ficheros INI de usuario. El valor por omisión es 300 segundos (5 minutos).



Dónde se puede realizar un ajuste de configuración

Estos modos determinan cuándo y dónde se debe o no asignar una directiva de PHP, y cada directiva del manual hace referencia a uno de estos modos. Por ejemplo, algunos ajustes pueden establecerse en scripts de PHP usandoini_set(), mientras que otros requieren hacerlo enphp.inio enhttpd.conf.

Por ejemplo, el ajusteoutput_bufferingesPHP_INI_PERDIRpor tanto no puede establecerse usandoini_set(). Sin embargo, la directivadisplay_errorsesPHP_INI_ALLpor tanto se puede establecer en cualquier lugar, incluso conini_set().

Definición de los modos PHP_INI_*
ModoSignificado
PHP_INI_USERLa entrada se puede establecer en scripts de usuario (como conini_set()) o en elregistro de Windows. Desde PHP 5.3, la entrada puede ser establecida en.user.ini
PHP_INI_PERDIRLa entrada se puede establecer enphp.ini,.htaccess,httpd.confo.user.ini(desde PHP 5.3)
PHP_INI_SYSTEMLa entrada se puede establecer enphp.inio enhttpd.conf
PHP_INI_ALLLa entrada se puede establecer en cualquier lugar



Cómo cambiar los ajustes de configuración

Ejecutar PHP como un módulo de Apache

Cuando se usa PHP como un módulo de Apache, se pueden cambiar los ajustes de configuración usando directivas en los ficheros de configuración de Apache (p.ej.httpd.conf) y en los ficheros.htaccess. Se necesitarán los privilegios "AllowOverride Options" o "AllowOverride All" para poder hacerlo.

Existen varias directivas de Apache que permiten cambiar la configuración de PHP desde los propios ficheros de configuración de Apache. Para un listado las directivas que sonPHP_INI_ALL,PHP_INI_PERDIR, oPHP_INI_SYSTEM, consulte el apéndice de laLista de directivas de php.ini.

php_valuenombrevalor

Establece el valor de la directiva especificada. Sólo puede usarse con las directivas de tipoPHP_INI_ALLyPHP_INI_PERDIR. Para borrar un valor previamente establecido, usenonecomo valor.

Nota:No usephp_valuepara establecer valores boolean. Debe usarse en su lugarphp_flag(ver más abajo).

php_flagnombreon|off

Usado para establecer una directiva de configuración de tipo boolean. Sólo puede usarse con las directivas de tipoPHP_INI_ALLyPHP_INI_PERDIR.

php_admin_valuenombrevalor

Establece el valor de la directiva especificada. Estono se puede usaren ficheros.htaccess. Ninguna directiva establecida conphp_admin_valuepodrá ser sobrescrita por.htaccesso porini_set(). Para borrar un valor establecido previamente usenonecomo valor.

php_admin_flagnombreon|off

Usado para establecer una directiva de configuración de tipo boolean. Estono se puede usaren ficheros.htaccess. Ninguna directiva establecida conphp_admin_flagpodrá ser sobrescrita por.htaccesso porini_set().

Ejemplo #1 Ejemplo de configuración de Apache

<IfModule mod_php5.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>

Precaución

Las constantes de PHP no existen fuera de PHP. Por ejemplo, enhttpd.confno se pueden usar constantes de PHP tales comoE_ALLoE_NOTICEpara establecer la directivaerror_reportingpuesto que no tendrán ningún significado y se evaluarán como0. Use en su lugar la máscara de bits asociada. Estas constantes sí pueden ser usadas enphp.ini

Cambiar la configuración de PHP a través del registro de Windows

Cuando se ejecuta PHP en Windows, se pueden modificar los valores de configuración a nivel de directorio usando el registro de Windows. Los valores de configuración se almacenan en la clave de registroHKLM\SOFTWARE\PHP\Per Directory Values, en las subclaves correspondientes a los nombres de ruta. Por ejemplo, los valores de configuración para el directorioc:\inetpub\wwwrootse almacenarían en la claveHKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot. Los ajustes para el directorio estarán activos para cualquier script dentro de este directorio o en cualquiera de sus subdirectorios. Los valores bajo esta clave deberían tener el nombre de la directiva de configuración de PHP y el valor como string. Las constantes de PHP usadas como valor no serán procesadas. En cualquier caso, únicamente los valores de configuración modificables dePHP_INI_USERpodrán establecerse con este método, mientras que los valores dePHP_INI_PERDIRno.

Otras interfaces a PHP

Independientemente de cómo ejecute PHP, se pueden cambiar determinados valores de los scripts en tiempo de ejecución medianteini_set(). Consulte la documentación de la páginaini_set()para más información.

Si está interesado en una lista completa de los ajustes de configuración en su sistema con sus valores actuales, puede ejecutar la funciónphpinfo(), y consultar la página mostrada. Puede también acceder a los valores de directivas de configuración concretas usandoini_get()oget_cfg_var().





Referencia del lenguaje


Sintaxis básica

Tabla de contenidos


Etiquetas de PHP

Cuando PHP analiza un fichero, busca las etiquetas de apertura y cierre, que son<?phpy?>, y que indican a PHP dónde empezar y finalizar la interpretación del código. Este mecanismo permite embeber a PHP en todo tipo de documentos, ya que todo lo que esté fuera de las etiquetas de apertura y cierre de PHP será ignorado por el analizador.

PHP también permite la etiqueta de apertura abreviada<?(la cual está desaconsejada debido a que sólo está disponible si se habilita con la directivashort_open_tagdel fichero de configuraciónphp.ini, o si PHP se configuró con la opción--enable-short-tags).

Si un fichero contiene solamente código de PHP, es preferible omitir la etiqueta de cierre de PHP al final del mismo. Así se previene la adición de espacios en blanco o nuevas líneas accidentales después de la etiqueta de cierre, lo cual causaría efectos no deseados debido a que PHP comenzará la salida del búfer cuando no había intención por parte del programador de enviar ninguna salida en ese punto del script.

<?php
echo"Hola mundo";

// ... más código

echo"Última sentencia";

// el script finaliza aquí sin etiqueta de cierre de PHP

Historial de cambios
VersiónDescripción
7.0.0Se eliminaron de PHP las etiquetas de ASP<%,%>,<%=, y la etiqueta de script<script language="php">.
5.4.0La etiqueta <?= siempre está disponible independientemente del ajuste ini short_open_tag.



Salir de HTML

Cualquier cosa fuera de un par de etiquetas de apertura y cierre es ignorado por el intérprete de PHP, lo que permite que los ficheros de PHP tengan contenido mixto. Esto hace que PHP pueda ser embebido en documentos HTML para, por ejemplo, crear plantillas.

<p>Esto va a ser ignorado por PHP y mostrado por el navegador.</p>
<?phpecho'Mientras que esto va a ser interpretado.';?>
<p>Esto también será ignorado por PHP y mostrado por el navegador.</p>
Este ejemplo funciona como estaba previsto, porque cuando PHP intercepta las etiquetas de cierre ?>, simplemente comienza a imprimir cualquier cosa que encuentre (a excepción de una nueva línea inmediatamente después; véase laseparación de instrucciones) hasta que dé con otra etiqueta de apertura a menos que se encuentre en mitad de una sentencia condicional, en cuyo caso el intérprete determinará el resultado de la condición antes de tomar una decisión de qué es lo que tiene que saltar. Vea el siguiente ejemplo.

Empleo de estructuras con condiciones

Ejemplo #1 Salida avanzada usando condiciones

<?phpif ($expresión==true):?>
Esto se mostrará si la expresión es verdadera.
<?phpelse:?>
En caso contrario se mostrará esto.
<?phpendif;?>
En este ejemplo, PHP saltará los bloques donde la condición no se cumpla, incluso si están fuera de las etiquetas de apertura/cierre de PHP, los saltará según la condición debido a que el intérprete salta los bloques contenidos dentro de una condición que no se cumpla.

Para imprimir bloques de texto grandes, es más eficiente abandonar el modo intérprete de PHP que enviar todo el texto a través deechooprint.

En PHP 5 existen hasta cinco pares de etiquetas de apertura y cierre diferentes, dependiendo de la configuración de PHP. Dos de estas,<?php ?>y<script language="php"> </script>, siempre están disponibles. También existe una etiqueta echo abreviada,<?= ?>, que siempre está disponible en PHP 5.4.0 y posteriores.

Las otras dos son las etiquetas abreviadas y las etiquetas al estilo deASP. De por sí, aunque algunos encuentran prácticas, las etiquetas abreviadas y las etiquetas al estiloASPson menos portables, no recomendándose por lo general.

Nota:

Observe también que si se está embebiendo PHP dentro de XML o XHTML será necesario usar las etiquetas <?php ?> para seguir los estándares.

PHP 7 elimina el soprte para las etiquetasASPy<script language="php">. Por tanto, para maximizar la compatibilidad, se recomienda solamente el empleo de<?php ?>y<?= ?>al escribir código de PHP.

Ejemplo #2 Etiquetas de apertura y de cierre de PHP

1.<?phpecho'si quiere proveer código de PHP a documentos XHTML o XML,
emplee estas etiquetas'
;?>

2. Puede emplear la etiqueta echo abreviada para<?='imprimir esta cadena'?>.
Siempre está habilitada en PHP 5.4.0 y posterior, y es equivalente a
<?phpecho'imprimir esta cadena'?>.

3. <? echo 'este código está dentro de etiquetas abreviadas, aunque sólo '.
'funcionará si short_open_tag está habilitada'; ?>

4. <script language="php">
echo 'a algunos editores (como FrontPage) no les gustan
las instruciones de procesamiento dentro de estas etiquetas';
</script>
Esta sintaxis ha sido eliminada en PHP 7.0.0.

5. <% echo 'Opcionalmente, se pueden emplear las etiquetas al estilo de ASP'; %>
El código dentro de estas etiquetas <%= $variable; %> es una abreviatura para este código <% echo $variable; %>
Ambas sintaxis han sido eliminadas en PHP 7.0.0.

Las etiquetas abreviadas (ejemplo tres) solamente están disponibles cuando se activan mediante la directivashort_open_tagdel fichero de configuraciónphp.inio si PHP se configuró con la opción--enable-short-tags.

Las etiquetas de estilo deASP(ejemplo cinco) solamente están disponibles cuando se activan mediante la directivaasp_tagsdel fichero de configuraciónphp.ini. Han sido eliminadas en PHP 7.0.0.

Nota:

Debe evitarse el uso de etiquetas abreviadas cuando se desarrollen aplicaciones o bibliotecas que estén pensadas para su redistribución o despliegue en servidores de PHP que no estén bajo su control, porque puede que las etiquetas abreviadas no estén admitidas en un servidor determinado. Por portabilidad y código redistribuible, asegúrese de no usar etiquetas abreviadas.

Nota:

En PHP 5.2 y anteriores, el analizador no permite que un fichero contenga únicamente la etiqueta de apertura<?php. A partir de PHP 5.3 sí se permite, siempre que existan uno o más caracteres espacio en blanco después de la etiqueta de apertura.

Nota:

Desde PHP 5.4, la etiqueta de echo abreviada<?=siempre es aceptada y válida, independientemente de la configuración deshort_open_tag.



Separación de instrucciones

Como en C o en Perl, PHP requiere que las instrucciones terminen en punto y coma al final de cada sentencia. La etiqueta de cierre de un bloque de código de PHP automáticamente implica un punto y coma; no es necesario usar un punto y coma para cerrar la última línea de un bloque de PHP. La etiqueta de cierre del bloque incluirá la nueva línea final inmediata si está presente.

<?php
echo'Esto es una prueba';
?>

<?phpecho'Esto es una prueba'?>

<?phpecho'Hemos omitido la última etiqueta de cierre';

Nota:

La etiqueta de cierre de un bloque de PHP es opcional al final de un fichero, y en algunos casos es útil omitirla cuando se usaincludeorequire, para que no se produzcan espacios en blanco al final de los ficheros, pudiéndose aún añadir así cabeceras para la respuesta posterior. También es práctico si se utiliza la salida del buffer y no se desean espacios en blanco no deseados al final de las partes generadas por ficheros incluídos.



Comentarios

PHP admite comentarios al estilo de 'C', 'C++' y de consola de Unix (estilo de Perl). Por ejemplo:

<?php
echo'Esto es una prueba';// Esto es un comentario al estilo de c++ de una sola línea
/* Esto es un comentario multilínea
y otra lína de comentarios */
echo'Esto es otra prueba';
echo
'Una prueba final';# Esto es un comentario al estilo de consola de una sola línea
?>

Los comentarios al estilo de "una sola línea" solo comentan hasta el final de la línea o del bloque actual de código de PHP, lo primero que suceda. Esto implica que el código HTML después de// ... ?>o# ... ?>SERÁ impreso: ?> sale del modo PHP y vuelve al modo HTML, por lo que//o#no pueden influir en eso. Si la directiva de configuraciónasp_tagsestá activada, actúa igual que// %>y# %>. Sin embargo, la etiqueta</script>no sale del modo PHP en un comentario de una sola línea.

<h1>Esto es un<?php# echo 'simple';?>ejemplo</h1>
<p>El encabezado anterior dirá 'Esto es un ejemplo'.</p>

Los comentarios al estilo de 'C' finalizan con el primer*/que se encuentre. Asegúrese de no anidar comentarios al estilo de 'C'. Es muy fácil cometer este error cuando se intenta comentar un bloque grande de código.

<?php
/*
echo 'Esto es una prueba'; /* Este comentario causará un problema*/
*/
?>




Tipos

Tabla de contenidos


Introducción

PHP admite diez tipos primitivos.

Cuatro tipos escalares:

  • boolean
  • integer
  • float(número de punto flotante, también conocido comodouble)
  • string

Cuatro tipos compuestos:

Y finalmente dos tipos especiales:

  • resource
  • NULL

Puede que existan aún algunas referencias al tipo "double" en el manual. Considere al tipo double como float; los dos nombres existen sólo por razones históricas.

El tipo de una variable usualmente no lo declara el programador; al contrario, es decidido en tiempo de ejecución por PHP dependiendo del contexto en el que se emplea dicha variable.

Nota:Para comprobar el tipo y el valor de unaexpresión, utilice la funciónvar_dump().

Para obtener una representación legible por humanos de un tipo con propósitos de depuración, use la funcióngettype(). Para comprobar un cierto tipo,noempleegettype(), si no las funcionesis_tipo. Algunos ejemplos:

<?php
$un_bool
=TRUE;// un valor booleano
$un_str="foo";// una cadena de caracteres
$un_str2='foo';// una cadena de caracteres
$un_int=12;// un número entero

echogettype($un_bool);// imprime: boolean
echogettype($un_str);// imprime: string

// Si este valor es un entero, incrementarlo en cuatro
if (is_int($un_int)) {
$un_int+=4;
}

// Si $un_bool es una cadena, imprimirla
// (no imprime nada)
if (is_string($un_bool)) {
echo
"Cadena:$un_bool";
}
?>

Para forzar la conversión de una variable a un cierto tipo, puedeamoldarla variable o usar la funciónsettype()con ella.

Observe que una variable puede ser evaluada con valores diferentes en ciertas situaciones, dependiendo del tipo que posea en cada momento. Para más información, lea la sección sobreManipulación de tipos.Las tablas de comparación de tipospueden resultar útiles también, ya que muestran ejemplos de varias comparaciones relacionadas con tipos.



Booleanos

Este es el tipo más simple. Unbooleanexpresa un valor que indica verdad. Puede sertrue(verdadero) ofalse(falso).

Sintaxis

Para especificar un literal de tipobooleanse emplean las constantestrueofalse. Ambas no son susceptibles a mayúsculas y minúsculas.

<?php
$foo
=True;// asigna el valor TRUE a $foo
?>

Usualmente, el resultado de unoperadorque devuelve un valor de tipobooleanes pasado a unaestructura de control.

<?php
// == es un operador que comprueba la
// igualdad y devuelve un booleano
if ($accion=="mostrar_version") {
echo
"La versión es 1.23";
}

// esto no es necesario...
if ($mostrar_separadores==TRUE) {
echo
"<hr>\n";
}

// ...porque se puede escribir simplemente:
if ($mostrar_separadores) {
echo
"<hr>\n";
}
?>

Conversión a booleano

Para convertir explícitamente un valor al tipoboolean, use los amoldamientos(bool)o(boolean). Sin embargo, en la mayoría de casos es innecesario el amoldamiento, ya que un valor será convertido automáticamente si un operador, función o estructura de control requiere un argumento de tipoboolean.

Véase también laManipulación de tipos.

Cuando se realizan conversiones aboolean, los siguientes valores se consideranfalse:

Cualquier otro valor se considera comotrue(incluido cualquierresourceyNAN).

Advertencia

-1se consideratrue, como cualquier otro número distinto de cero (ya sea negativo o positivo).

<?php
var_dump
((bool)"");// bool(false)
var_dump((bool)1);// bool(true)
var_dump((bool) -2);// bool(true)
var_dump((bool)"foo");// bool(true)
var_dump((bool)2.3e5);// bool(true)
var_dump((bool) array(12));// bool(true)
var_dump((bool) array());// bool(false)
var_dump((bool)"false");// bool(true)
?>


Números enteros (Integers)

Un número entero (ointeger) es un número del conjunto ℤ = {..., -2, -1, 0, 1, 2, ...}.

Véase también:

Sintaxis

Losintegerpueden especificarse mediante notación decimal (base 10), hexadecimal (base 16), octal (base 8) o binaria (base 2), opcionalmente precedidos por un signo (- o +).

Los literales de tipointegerbinarios están disponibles desde PHP 5.4.0.

Para utilizar la notación octal, se antepone al número un0(cero). Para utilizar la notación hexadecimal, se antepone al número0x. Para utilizar la notación binaria, se antepone al número0b.

Ejemplo #1 Literales de números enteros

<?php
$a
=1234;// número decimal
$a= -123;// un número negativo
$a=0123;// número octal (equivale a 83 decimal)
$a=0x1A;// número hexadecimal (equivale a 26 decimal)
$a=0b11111111;// número binario (equivale al 255 decimal)
?>

Formalmente, la estructura de los literales de tipointegeres:

decimal     : [1-9][0-9]*
            | 0

hexadecimal : 0[xX][0-9a-fA-F]+

octal       : 0[0-7]+

binario     : 0b[01]+

entero      : [+-]?decimal
            | [+-]?hexadecimal
            | [+-]?octal
            | [+-]?binario

El tamaño de unintegerdepende de la plataforma, aunque el valor usual es un valor máximo de aproximadamente dos mil millones (esto es, 32 bits con signo). Las plataformas de 64 bits normalmente tienen un valor máximo de aproximadamente 9E18, excepto en Windows antes de PHP 7, que siempre es de 32 bits. PHP no tiene soporte para el tipointegersin signo. El tamaño de unintegerse puede determinar mediante la constantePHP_INT_SIZE, y el valor máximo mediante la constantePHP_INT_MAXdesde PHP 4.4.0 y PHP 5.0.5, y el valor mínimo mediante la constantePHP_INT_MINdesde PHP 7.0.0.

Advertencia

Antes de PHP 7, si a unintegeroctal se le proporcionaba un dígito no válido (esto es, 8 o 9), se ignoraba el resto del número. Desde PHP 7, se emite un error de análisis.

Desbordamiento de enteros

Si PHP encuentra un número fuera de los límites de uninteger, se interpretará en su lugar como un valor de tipofloat. También, una operación cuyo resultado sea un número fuera de los límites de unintegerdevolverá en su lugar un valor de tipofloat.

Ejemplo #2 Desbordamiento de enteros en sistemas de 32 bit

<?php
$número_grande
=2147483647;
var_dump($número_grande);// int(2147483647)

$número_grande=2147483648;
var_dump($número_grande);// float(2147483648)

$millón=1000000;
$número_grande=50000*$millón;
var_dump($número_grande);// float(50000000000)
?>

Ejemplo #3 Desbordamiento de enteros en sistemas de 64 bit

<?php
$número_grande
=9223372036854775807;
var_dump($número_grande);// int(9223372036854775807)

$número_grande=9223372036854775808;
var_dump($número_grande);// float(9.2233720368548E+18)

$millón=1000000;
$número_grande=50000000000000*$millón;
var_dump($número_grande);// float(5.0E+19)
?>

No existe el operador de división deintegeren PHP.1/2produce elfloat0.5. El valor puede ser convertido a unintegerredondeándolo a cero, o mediante la funciónround()que permite un mayor control sobre el redondeo.

<?php
var_dump
(25/7);// float(3.5714285714286)
var_dump((int) (25/7));// int(3)
var_dump(round(25/7));// float(4)
?>

Conversión a números enteros

Para convertir explícitamente un valor al tipointegerse puede emplear tanto(int)como(integer). Sin embargo, la mayoría de las veces la conversión no es necesaria, ya que un valor es convertido de forma automática cuando un operador, función o estructura de control requiera un argumento de tipointeger. Un valor también puede ser convertido al tipointegermediante la funciónintval().

Si unresourcees convertido a uninteger, el resultado será el número de recurso único asignado alresourcepor PHP durante la ejecución.

Consulte también laManipulación de tipos.

Desdebooleanos

falseproducirá0(cero), ytrueproducirá1(uno).

Desdenúmeros de punto flotante

Cuando se convierte unfloata uninteger, el número será redondeadohacia cero.

Si el valor de tipo float esta por debajo de los límites de uninteger(normalmente+/- 2.15e+9 = 2^31en plataformas de 32 bits y+/- 9.22e+18 = 2^63en plataformas de 64 bits distintas de Windows), el resultado es indefinido, debido a quefloatno tiene la precisión suficiente para ofrecer el resultado como unintegerexacto. No se mostrará ninguna advertencia, ni siquiera un aviso, cuando esto ocurra.

Nota:

A partir de PHP 7.0.0,0, en lugar de ser indefinidos y dependientes de la plataforma, NaN e Infinity siempre serán cero al amoldarlos ainteger.

Advertencia

Nunca se debe convertir una fracción desconocida a uninteger, ya que a veces puede conducir a resultados inesperados.

<?php
echo (int) ( (0.1+0.7) *10);// ¡muestra 7!
?>

Consulte también laadvertencia sobre la precisión de float

Desde cadenas de caracteres

ConsulteConversión de string a números

Desde otros tipos

Precaución

El comportamiento de la conversión deintegera otros tipos es indefinido.Noconfíe en ningún comportamiento observado, ya que puede cambiar sin previo aviso.



Números de punto flotante

Los números de punto flotante (también conocidos como "de coma flotante" en español, y "floats" en inglés) pueden ser especificados usando cualquiera de las siguientes sintaxis:

<?php
$a
=1.234;
$b=1.2e3;
$c=7E-10;
$d=1_234.567;// a partir de PHP 7.4.0
?>

Formalmente a partir de PHP 7.4.0 (anteriormente, no se permitían los guiones bajos):

LNUM          [0-9]+(_[0-9]+)*
DNUM          ([0-9]*(_[0-9]+)*[\.]{LNUM}) | ({LNUM}[\.][0-9]*(_[0-9]+)*)
EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})

El tamaño de un 'float' depende de la plataforma, aunque un valor común consiste en un máximo de aproximadamente 1.8e308 con una precisión cercana a los 14 dígitos decimales (el formato de 64 bit del IEEE).

Advertencia

Precisión del punto flotante

Los números de punto flotante tienen una precisión limitada. Aunque depende del sistema, PHP típicamente utiliza el formato de doble precisión IEEE 754, el cual dará un error relativo máximo por aproximación del orden de 1.11e-16. Las operaciones aritméticas elementales no podrán generar grandes errores y, por supuesto, se han de considrar los errores por propagación al componer varias operaciones.

Adicionalmente, los numeros racionales que son representables exactamente como números de punto flotante en base 10, como0.1o0.7, no tienen una representación exacta como números de punto flotante en base 2, que es la base empleada internamente, sin importar el tamaño de la mantisa. Por lo tanto, no se pueden convertir en sus equivalentes binarios internos sin una pequeña pérdida de precisión. Esto puede conducir a resultados confusos: Por ejemplo,floor((0.1+0.7)*10)usualmente devolverá7en lugar del8previsto, ya que la representación interna será algo así como7.9999999999999991118....

Por tanto, nunca se ha de confiar en resultados de números flotantes hasta el último dígito, y no comparar la igualdad de números de punto flotante directamente. Si fuera necesaria una mayor precisión, están disponibles lasfunciones matemáticas de precisión arbitrariay las funciones degmp.

Para una explicación "simple", véase la» guía del punto flotanteque también se titula "¿Por qué no sale la cuenta?"

Conversión al tipo float

Para más información sobre las conversiones destringafloat, véase laConversión de cadenas a números. Para valores de otros tipos, la conversión es la misma que si el valor hubiese sido convertido primero aintegery luego afloat. Véase laConversión a al tipo integerpara más información. A partir de PHP 5, se genera un aviso si se intenta convertir unobjectafloat.

Comparación del tipo float

Como se indica en la advertencia anterior, comprobar la igualdad de valores de punto flotante es problemático debido a la forma en que se representan internamente. Sin embargo, hay maneras de hacer comparaciones de los valores de punto flotante que evitan estas limitaciones.

Para comprobar la igualdad de valores de punto flotante, se utiliza un límite superior en el error relativo debido al redondeo. Este valor se conoce como el épsilon de la máquina o unidad de redondeo, y es la menor diferencia aceptable en los cálculos.

$ay$bson iguales en 5 dígitos de precisión.

<?php
$a
=1.23456789;
$b=1.23456780;
$épsilon=0.00001;

if(
abs($a-$b) <$épsilon) {
echo
"true";
}
?>

NaN

Algunas operaciones numéricas pueden resultar en un valor representado por la constanteNAN. Este resultado representa un valor no definido o no representable mediante cálculos de punto flotante. Cualquier comparación, ya sea estricta o no, de este valor con cualquier otro valor, incluido él mismo, pero exceptotrue, tendrá un resultado defalse.

Ya queNANrepresenta cualquier número de diferentes valores,NANno debería compararse con otros valores, incluido él mismo; en su lugar debería comprobarse usando la funciónis_nan().



Cadenas de caracteres (Strings)

Unstring, o cadena, es una serie de caracteres donde cada carácter es lo mismo que un byte. Esto significa que PHP solo admite un conjunto de 256 caracteres, y de ahí que no ofrezca soporte nativo para Unicode. Véanse losdetalles del tipo string.

Nota:Unstringpuede llegar a alcanzar hasta 2 GB de tamaño (2147483647 bytes máximo).

Sintaxis

Un literal de tipostringse puede especificar de cuatro formas diferentes:

Entrecomillado simple

La manera más sencilla de especificar unstringes delimitarlo con comillas simples (el carácter').

Para especificar una comilla simple literal, se ha de escapar con una barra invertida (\). Para especificar una barra invertida literal, se duplica (\\). Todas las demás instancias de barras invertidas serán tratadas como una barra invertida literal: esto significa que otras secuencias de escape que podrían utilizarse, tales como\ro\n, serán mostradas literalmente tal y como se especifican, en lugar de tener cualquier otro significado especial.

Nota:A diferencia de las sintaxis deentrecomillado dobleyheredoc, lasvariablesy las sentencias de escape para caracteres especialesnose expandirán cuando estén incluidas dentro de unstringentre comillas simples.

<?php
echo'Esto es una cadena sencilla';

echo
'También se pueden incluir nuevas líneas en
un string de esta forma, ya que es
correcto hacerlo así'
;

// Resultado: Arnold una vez dijo: "I'll be back"
echo'Arnold una vez dijo: "I\'ll be back"';

// Resultado: Ha borrado C:\*.*?
echo'Ha borrado C:\\*.*?';

// Resultado: Ha borrado C:\*.*?
echo'Ha borrado C:\*.*?';

// Resultado: Esto no se expandirá: \n una nueva línea
echo'Esto no se expandirá: \n una nueva línea';

// Resultado: Las variables $tampoco se $expandirán
echo'Las variables $tampoco se $expandirán';
?>

Entrecomillado doble

Si unstringestá delimitado con comillas dobles ("), PHP interpretará las siguientes secuencias de escape como caracteres especiales:

Caracteres escapados
SecuenciaSignificado
\navance de línea (LF o 0x0A (10) en ASCII)
\rretorno de carro (CR o 0x0D (13) en ASCII)
\ttabulador horizontal (HT o 0x09 (9) en ASCII)
\vtabulador vertical (VT o 0x0B (11) en ASCII) (desde PHP 5.2.5)
\eescape (ESC o 0x1B (27) en ASCII) (desde PHP 5.4.4)
\favance de página (FF o 0x0C (12) en ASCII) (desde PHP 5.2.5)
\\barra invertida
\$signo de dólar
\"comillas dobles
\[0-7]{1,3}la secuencia de caracteres que coincida con la expresión regular es un carácter en notación octal, que silenciosamente desborda para encajar en un byte (p.ej. "\400" === "\000")
\x[0-9A-Fa-f]{1,2}la secuencia de caracteres que coincida con la expresión regular es un carácter en notación hexadecimal
\u{[0-9A-Fa-f]+}la secuencia de caracteres que coincida con la expresión regular es un punto de código de Unicode, la cual será imprimida al string como dicha representación UTF-8 del punto de código (añadido en PHP 7.0.0)

Al igual que en el entrecomillado simple de unstring, escapar cualquier otro carácter puede dar lugar a que se muestre también la barra invertida. Antes de PHP 5.1.1, no se mostraba la barra invertida de\{$var}.

La característica más importante del entrecomillado doble de unstringes el hecho de que se expanden los nombres de las variables. Consulte elanálisis de stringpara más detalles.

Heredoc

Una tercera forma de delimitar unstringes mediante la sintaxis heredoc:<<<. Después de este operador, se deberá proporcionar un identificador y justo después una nueva línea. A continuación va el propiostring, y para cerrar la notación se pone el mismo identificador.

El identificador de cierredebeempezar en la primera columna de la nueva línea. Asimismo, el identificador debe seguir las mismas reglas de nomenclatura de las etiquetas en PHP: debe contener solo caracteres alfanuméricos y guiones bajos, y debe empezar con un carácter alfabético o un guión bajo.

Advertencia

Es muy importante señalar que la línea con el identificador de cierre no debe contener ningún otro carácter, excepto un punto y coma (;). Esto, en especial, significa que el identificadorno debe estar sangrado, y que no debe existir ningún espacio ni tabulación antes o después del punto y coma. Es muy importante observar que el primer carácter antes del identificador de cierre debe ser un salto de línea definido por el sistema operativo local. Este es\nen los sistemas UNIX, incluyendo Mac OS X. Al delimitador de cierre le ha de seguir tambíen una nueva línea.

Si se rompe esta regla y el identificador de cierre no está "limpio", no será considerado como un identificador de cierre, por lo que PHP continuará buscando uno. Si no se encuentra ningún identificador de cierre apropiado antes del final del fichero, se producirá un error de análisis en la última línea.

No se puede emplear Heredoc para inicializar las propiedades de una clase. Desde PHP 5.3, esta limitación es válida solamente para un heredoc que contengan variables.

Ejemplo #1 Ejemplo no válido

<?php
classfoo{
public
$bar= <<<EOT
bar
EOT;
}
?>

El texto heredoc se comporta como unstringentre comillas dobles, pero sin tener comillas dobles. Esto significa que no es necesario escapar las comillas en un heredoc, aunque se puede seguir empleando los códigos de escape indicados arriba. Pese a que las variables son expandidas, se debe tener el mismo cuidado al expresar variables complejas en un heredoc que en unstring.

Ejemplo #2 Ejemplo de entrecomillado de string en Heredoc

<?php
$str
= <<<EOD
Ejemplo de una cadena
expandida en varias líneas
empleando la sintaxis heredoc.
EOD;

/* Un ejemplo más complejo con variables. */
classfoo
{
var
$foo;
var
$bar;

function
foo()
{
$this->foo='Foo';
$this->bar= array('Bar1','Bar2','Bar3');
}
}

$foo= newfoo();
$nombre='MiNombre';

echo <<<EOT
Mi nombre es "$nombre". Estoy escribiendo un poco de$foo->foo.
Ahora, estoy escribiendo un poco de
{$foo->bar[1]}.
Esto debería mostrar una 'A' mayúscula: \x41
EOT;
?>

El resultado del ejemplo sería:

Mi nombre es "MiNombre". Estoy escribiendo un poco de Foo.
Ahora, estoy escribiendo un poco de Bar2.
Esto debería mostrar una 'A' mayúscula: A

También se puede emplear la sintaxis Heredoc para pasar datos como argumentos de una función:

Ejemplo #3 Ejemplo de Heredoc en argumentos

<?php
var_dump
(array(<<<EOD
foobar!
EOD
));
?>

Desde PHP 5.3.0, es posible inicializar variables estáticas y propiedades/constantes de clase mediante la sintaxis Heredoc:

Ejemplo #4 Usar Heredoc para inicializar valores estáticos

<?php
// Variables estáticas
functionfoo()
{
static
$bar= <<<LABEL
Nada aquí...
LABEL;
}

// Propiedades/constantes de clase
classfoo
{
const
BAR= <<<FOOBAR
Ejemplo de constante
FOOBAR;

public
$baz= <<<FOOBAR
Ejemplo de propiedad
FOOBAR;
}
?>

PHP 5.3.0 también introdujo la posibilidad de entrecomillar el identificador de apertura en Heredoc:

Ejemplo #5 Emplear comillas dobles en Heredoc

<?php
echo <<<"FOOBAR"
¡Hola Mundo!
FOOBAR;
?>

Nowdoc

Nowdoc es a los string con comillas simples lo mismo que Heredoc lo es a los string con comillas dobles. Un nowdoc se especifica de forma análoga a un heredoc, perono se realiza ningún análisisdentro del nowdoc. La construcción es ideal para embeber código de PHP o grandes fragmentos de texto sin necesidad de escaparlos. Comparte algunas características comunes con la construcción<![CDATA[ ]]>de SGML, donde se declara un bloque de texto que no se analiza.

Un nowdoc se identifica con la misma secuencia empleada para heredoc,<<<, pero el identificador que le sigue está delimitado con comillas simples, p.ej.,<<<'EOT'. Todas las reglas para los identificadores de heredoc también son aplicables a los identificadores de nowdoc, especialmente aquellas que se refieren al empleo del identificador de cierre.

Ejemplo #6 Ejemplo de entrecomillado de string de Nowdoc

<?php
$str
= <<<'EOD'
Ejemplo de un string
expandido en varias líneas
empleando la sintaxis nowdoc.
EOD;

/* Un ejemplo más complejo con variables. */
classfoo
{
public
$foo;
public
$bar;

function
foo()
{
$this->foo='Foo';
$this->bar= array('Bar1','Bar2','Bar3');
}
}

$foo= newfoo();
$nombre='MiNombre';

echo <<<'EOT'
Mi nombre es "$nombre". Estoy escribiendo un poco de $foo->foo.
Ahora, estoy escribiendo un poco de {$foo->bar[1]}.
Esto debería mostrar una 'A' mayúscula: \x41
EOT;
?>

El resultado del ejemplo sería:

Mi nombre es "$nombre". Estoy escribiendo un poco de $foo->foo.
Ahora, estoy escribiendo un poco de {$foo->bar[1]}.
Esto debería mostrar una 'A' mayúscula: \x41

Ejemplo #7 Ejemplo de datos estáticos

<?php
classfoo{
public
$bar= <<<'EOT'
bar
EOT;
}
?>

Nota:

El soporte para Nowdoc se añadió en PHP 5.3.0.

Análisis de variables

Cuando unstringes especificado mediante comillas dobles o mediante heredoc, lasvariablesque haya dentro de dicho string se analizarán.

Existen dos tipos de sintaxis: unasimpley otracompleja. La sintaxis simple es la más empleada y práctica. Proporciona una forma de embeber una variable, un valor de unarrayo una propiedad de unobjectdentro de unstringcon el mínimo esfuerzo.

La sintaxis compleja puede ser reconocida por las llaves que delimitan la expresión.

Sintaxis simple

Si se encuentra un signo de dólar ($), el analizador tomará el mayor número de símbolos para formar un nombre de variable válido. Delimitar el nombre de la variable con llaves permite especificar explícitamente el final del nombre.

<?php
$jugo
="manzana";

echo
"Él tomó algo de jugo de$jugo.".PHP_EOL;
// Inválido. "s" es un carácter válido para un nombre de variable, pero la variable es $jugo.
echo"Él tomó algo de jugo hecho de$jugos.";
// Válido. Explícitamente especifica el final del nombre de la variable encerrándolo entre llaves:
echo"Él tomó algo de jugo hecho de${jugo}s."
?>

El resultado del ejemplo sería:

Él tomó algo de jugo de manzana.
Él tomó algo de jugo hecho de .
Él tomó algo de jugo hecho de manzanas.

De forma parecida, se puede analizar el índice de unarrayo la propiedad de unobject. Con los índices de los arrays, el corchete de cierre (]) marca el final del índice. La misma regla se puede aplicar a las propiedades de los objetos y a las variables simples.

Ejemplo #8 Ejemplo de sintaxis simple

<?php
$jugos
= array("manzana","naranja","koolaid1"=>"púrpura");

echo
"Él tomó algo de jugo de$jugos[0].".PHP_EOL;
echo
"Él tomó algo de jugo de$jugos[1].".PHP_EOL;
echo
"Él tomó algo de jugo$jugos[koolaid1].".PHP_EOL;

class
persona{
public
$john="John Smith";
public
$jane="Jane Smith";
public
$robert="Robert Paulsen";

public
$smith="Smith";
}

$persona= newpersona();

echo
"$persona->johntomó algo de jugo de$jugos[0].".PHP_EOL;
echo
"$persona->johnentonces dijo hola a$persona->jane.".PHP_EOL;
echo
"La esposa de$persona->johnsaludó a$persona->robert.".PHP_EOL;
echo
"$persona->robertsaludó a los dos$persona->smiths.";// No funcionará
?>

El resultado del ejemplo sería:

Él tomó algo de jugo de manzana.
Él tomó algo de jugo de naranja.
Él tomó algo de jugo púrpura.
John Smith tomó algo de jugo de manzana.
John Smith entonces dijo hola a Jane Smith.
La esposa de John Smith saludó a Robert Paulsen.
Robert Paulsen saludó a los dos .

Para casos más complejos se debe emplear la sintaxis compleja.

Sintaxis compleja (llaves)

Esta sintaxis no se llama compleja porque sea compleja, sino porque permite el empleo de expresiones complejas.

Cualquier variable escalar, elemento de array o propiedad de objeto con una representación de tipostringpuede ser incluido a través de esta sintaxis. Simplemente se escribe la expresión del mismo modo en que aparecería por fuera delstring, y delimitándola con{y}. Dado que{no puede ser escapado, esta sintaxis será reconocida únicamente cuando el$siga inmediatamente al{. Utilice{\$para obtener un{$literal. Algunos ejemplos para que quede más claro:

<?php
// Mostrar todos los errores
error_reporting(E_ALL);

$genial='fantástico';

// No funciona, muestra: Esto es { fantástico}
echo"Esto es {$genial}";

// Funciona, muestra: Esto es fantástico
echo"Esto es{$genial}";

// Funciona
echo"Este cuadrado tiene{$cuadrado->width}00 centímetros de lado.";


// Funciona, las claves entre comillas sólo funcionan usando la sintaxis de llaves
echo"Esto funciona:{$arr['clave']}";


// Funciona
echo"Esto funciona:{$arr[4][3]}";

// Esto no funciona por la misma razón que $foo[bar] es incorrecto fuera de un string.
// En otras palabras, aún funcionaría, pero solamente porque PHP primero busca una
// constante llamada foo; se emitirá un error de nivel E_NOTICE
// (constante no definida).
echo"Esto está mal:{$arr[foo][3]}";

// Funciona. Cuando se usan arrays multidimensionales, emplee siempre llaves que delimiten
// a los arrays cuando se encuentre dentro de un string
echo"Esto funciona:{$arr['foo'][3]}";

// Funciona.
echo"Esto funciona: ".$arr['foo'][3];

echo
"Esto también funciona:{$obj->valores[3]->nombre}";

echo
"Este es el valor de la variable llamada$nombre:{${$nombre}}";

echo
"Este es el valor de la variable llamada por el valor devuelto por getNombre():{${getNombre()}}";

echo
"Este es el valor de la variable llamada por el valor devuelto por \$objeto->getNombre():{${$objeto->getNombre()}}";

//No funciona, muestra: Esto es el valor devuelto por getNombre(): {getNombre()}
echo"Esto es el valor devuelto por getNombre(): {getNombre()}";
?>

Con esta sintaxis, también es posible acceder a las propiedades de una clase empleando variables dentro de un string.

<?php
classfoo{
var
$bar='Soy bar.';
}

$foo= newfoo();
$bar='bar';
$baz= array('foo','bar','baz','quux');
echo
"{$foo->$bar}\n";
echo
"{$foo->{$baz[1]}}\n";
?>

El resultado del ejemplo sería:

Soy bar.
Soy bar.

Nota:

Las funciones, llamadas a métodos, variables de clase estáticas y constantes de clases dentro de{$}funcionan desde PHP 5. Sin embargo, el valor accedido puede ser interpretado como el nombre de la variable en el ámbito en el que está definido el string. El empleo de simples llaves ({}) no servirá para acceder al valor devuelto por las funciones o métodos, o los valores de las constantes de clase o variables de clase estáticas.

<?php
// Mostrar todos los errores.
error_reporting(E_ALL);

class
cervezas{
const
refresco='zarzaparrilla';
public static
$ale='ipa';
}

$zarzaparrilla='A & W';
$ipa='Alexander Keith\'s';

// Funciona; muestra: Me gusta una A & W
echo"Me gusta una{${cervezas::refresco}}\n";

// También funciona; muestra: Me gusta una Alexander Keith's
echo"Me gusta una{${cervezas::$ale}}\n";
?>

Acceso a string y modificacion por caracteres

Se puede acceder y modificar los caracteres dentro de unstringespecificando el índice de base cero del carácter deseado después delstringempleando los corchetes dearray, como en$str[42]. Piense en unstringcomo unarrayde caracteres, en este caso. Las funcionessubstr()ysubstr_replace()pueden ser empleadas para extraer o reemplazar más de un carácter.

Nota:También se puede acceder a unstringutilizando llaves, como en$str{42}, con el mismo propósito.

Advertencia

Escribir en un índice fuera del rango rellenará el string con espacios. Los tipos que no sean integer son convertidos a integer. Los índices ilegales emiten un error de nivelE_NOTICE. Los índices negativos emiten un error de nivelE_NOTICEen la escritura, aunque se lea un string vacío. Sólo se emplea el primer carácter de un string asignado. La asignación de un string vacío asigna un byte NULL.

Advertencia

Internamente, los string de PHP son arrays de bytes. Por tanto, acceder o modificar un string utilizando los corchetes de array no es seguro con caracteres multibyte, dado que sólo se realiza con los string de codificaciones monobyte, como ISO-8859-1.

Ejemplo #9 Algunos ejemplos de string

<?php
// Obtener el primer carácter de un string
$str='Esto es una prueba.';
$primero=$str[0];

// Obtener el tercer carácter de un string
$tercero=$str[2];

// Obtener el último carácter de un string
$str='Esto sigue siendo una prueba.';
$último=$str[strlen($str)-1];

// Modificar el último carácter de un string
$str='Mira el mar';
$str[strlen($str)-1] ='l';

?>

A partir de PHP 5.4, los índices de string tienen que ser de tipo integer o integer en forma de string, si no, se emitirá una advertencia. Anteriormente, un índice como"foo"era convertido de manera silenciosa a0.

Ejemplo #10 Diferencias entre PHP 5.3 y PHP 5.4

<?php
$str
='abc';

var_dump($str['1']);
var_dump(isset($str['1']));

var_dump($str['1.0']);
var_dump(isset($str['1.0']));

var_dump($str['x']);
var_dump(isset($str['x']));

var_dump($str['1x']);
var_dump(isset($str['1x']));
?>

Salida del ejemplo anterior en PHP 5.3:

string(1) "b"
bool(true)
string(1) "b"
bool(true)
string(1) "a"
bool(true)
string(1) "b"
bool(true)

Salida del ejemplo anterior en PHP 5.4:

string(1) "b"
bool(true)

Warning: Illegal string offset '1.0' in /tmp/t.php on line 7
string(1) "b"
bool(false)

Warning: Illegal string offset 'x' in /tmp/t.php on line 9
string(1) "a"
bool(false)
string(1) "b"
bool(false)

Nota:

El acceso a variables de otros tipos (sin incluir arrays u objetos que implementen las interfaces apropiadas) utilizando[]o{}, silenciosamente retornanull.

Nota:

PHP 5.5 añadió soporte para acceder a caracteres dentro de literales de tipo string utilizando[]o{}.

Funciones y operadores útiles

Losstringpueden ser concatenados empleando el operador '.' (punto). Fíjese que el operador '+' (suma)noservirá para concatenar. Consulte losoperadores de stringpara más información.

Hay una serie de funciones útiles para la manipulación destring.

Consulte lasección de funciones de stringpara funciones generales, y lasfunciones de expresiones regulares compatibles con Perlpara características avanzadas de búsqueda y sustitución.

También existenfunciones para string de URL, y funciones para encriptar/desencriptar string (mcryptymhash).

Finalmente, también existen lasfunciones para el tipo carácter.

Conversión a string

Un valor puede convertirse a unstringempleando el molde(string)o mediante la funciónstrval(). La conversión automática astringtiene lugar en el ámbito de una expresión donde sea necesario unstring. Esto ocurre cuando se utilizan las funcionesechooprint, o cuando se compara una variable con unstring. Las secciones sobreTiposyManipulación de tiposlo aclararán. Consulte también la funciónsettype().

El valortruedel tipobooleanes convertido alstring"1". El valorfalsedel tipobooleanes convertido alstring""(el string vacío). Esto permite la conversión en ambos sentidos entre los valores de los tiposbooleanystring.

Unintegerofloates convertido a unstringque representa textualmente el número (incluyendo la parte exponencial para losfloat. Los números de punto flotante pueden ser convertidos mediante la notación exponencial (4.1E+6).

Nota:

El carácter para el punto decimal se define en el localismo del script (categoría LC_NUMERIC). Consulte la funciónsetlocale().

Losarrays siempre son convertidos alstring"Array". Debido a esto,echoyprintno pueden por sí mismos mostrar el contenido de unarray. Para ver un único elemento individualmente, utilice una construcción comoecho $arr['foo']. Vea los consejos de más abajo para mostrar el contenido completo.

Losobjecten PHP 4 siempre son convertidos alstring"Object". Para mostrar los valores de las propiedades de un objeto para su depuración, lea los párrafos siguientes. Para obtener el nombre de la clase de un objeto, emplee la funciónget_class(). A partir de PHP 5, se puede emplear el método__toStringcuando sea relevante.

Unresourcesiempre es convertido astringcon la estructura"Resource id #1", donde1es el número de recurso asignado alresourcepor PHP durante la ejecución. A pesar de que no se debe depender de la estructura exacta, debido a que está sujeta a cambios, siempre será única para un recurso dado dentro del tiempo de vida de un script en ejecución (es decir, una petición web o proceso CLI), por lo que no será reutilizada. Para obtener el tipo de unresource, emplee la funciónget_resource_type().

nullsiempre es convertido a un string vacío.

Como se indicó anteriormente, la conversión directa de unarray,objectoresourcea unstringno proporciona información útil acerca del valor más allá de su tipo. Consulte las funcionesprint_r()yvar_dump()para ver medios más efectivos de inspeccionar el contenido de estos tipos.

La mayoría de los valores de PHP pueden ser convertidos a unstringpara su almacenamiento permanente. Este método se denomina serialización, y es realizado mediante la funciónserialize(). Si el motor de PHP se construyó con soporte paraWDDX, los valores de PHP también pueden ser serializacos como texto XML bien formado.

Conversión de string a números

Cuando unstringes evaluado en un contexto numérico, el valor resultante y el tipo se determina como se explica a continuación.

Si elstringno contiene ninguno de los caracteres '.', 'e', o 'E', y el valor numérico está entre los límites del tipo integer (tal como está definido porPHP_INT_MAX), elstringserá evaluado como uninteger. En todos los demás casos será evaluado como unfloat.

El valor es dado por la parte inicial delstring. Si elstringempieza con un dato numérico válido, éste será el valor empleado. De lo contrario, el valor será 0 (cero). Un dato numérico válido es un signo opcional, seguido de uno o más dígitos (opcionalmente puede contener un punto decimal), seguido de un exponente opcional. El exponente es una 'e' o 'E' seguida de uno o más dígitos.

<?php
$foo
=1+"10.5";// $foo es float (11.5)
$foo=1+"-1.3e3";// $foo es float (-1299)
$foo=1+"bob-1.3e3";// $foo es integer (1)
$foo=1+"bob3";// $foo es integer (1)
$foo=1+"10 pequeños cerdos";// $foo es integer (11)
$foo=4+"10.2 pequeños cerditos";// $foo es float (14.2)
$foo="10.0 cerdos "+1;// $foo es float (11)
$foo="10.0 cerdos "+1.0;// $foo es float (11)
?>

Para más información sobre esta conversión, consulte la página del manual de Unix para a strtod(3).

Para probar cualesquiera de los ejemplos de esta sección, copie y péguelos e incluya la siguiente línea para ver lo que está sucediendo:

<?php
echo"\$foo==$foo; tipo : ".gettype($foo) ."<br />\n";
?>

No espere obtener el código de un carácter convirtiéndolo a un integer, como ocurre en C. Emplee las funcionesord()ychr()para convertir entre código códigos ASCII y caracteres.

Detalles del tipo string

En PHP, losstringse implementan como un array de bytes y con un número entero que indica la longitud del búfer. No posee ninguna información sobre cómo traducir esos bytes a caracteres, relegando esa tarea al programador. No existe ninguna limitación sobre los valores que pueden componer un string; en concreto, está permitido colocar bytes con valor0(“bytes NUL”) en cualquier posición del string (aunque existen algunas funciones, citadas en este manual como “no seguras a nivel binario”, que podrían rechazar estos string para aquellas bibliotecas que ignoren los datos que siguen a un byte NUL.)

Este comportamiento del tipo string justifica que no exista un tipo de dato "byte" en PHP – los string se encargan de esto. Las funciones que no devuelven datos de texto – por ejemplo, cualquier dato leído a partir de un socket de red – devolverán valores de tipo string.

Dado que PHP no obliga a utilizar ninguna condificación en particular, uno podría preguntarse cómo se codifican los literales de tipo string. Por ejemplo, ¿es el string"á"equivalente a"\xE1"(ISO-8859-1),"\xC3\xA1"(UTF-8, forma C),"\x61\xCC\x81"(UTF-8, forma D) o cualquier otra representación posible? La respuesta es que un string será codificado en cualquiera forma en que estuviera codificado el fichero del script. Por tanto, si un script estuviera escrito en ISO-8859-1, el string se codificará en ISO-8859-1, etc. Sin embargo, esto no es aplicable si está habilitado Zend Multibyte; en ese caso, el script podría estar escrito en cualquier codificación (la cual es declarada explícitamente o es detectada) para después convertirse a una determinada codificación interna, que será entonces la codificación usada para los literales de tipo string. Tenga presente que existen algunas limitaciones sobre la codificación del script (o en la codificación interna, si Zend Multibyte estuviera habilitado); esto suele significar que dicha codificación debería ser compatible con un superconjunto de ASCII, tal como UTF-8 o ISO-8859-1. Por contra, las codificaciones dependientes del estado donde se pueden utilizar los mismos valores de byte en estados de desplazamiento iniciales y no iniciales, podrían generar problemas.

Por supuesto, para poder ser útiles, las funciones que operen con texto podrían partir de unos supuestos sobre cómo está codificado el string. Desafortunadamente, respecto a esto existen muchas variaciones en las funciones de PHP:

  • Algunas funciones asumen que el string está codificado con una codificación de un único byte, por lo que no es necesario interpretar estos bytes como caracteres específicos. Este es el caso de, por ejemplo,substr(),strpos(),strlen()ostrcmp(). Otra forma de entender estas funciones es pensando que operan sobre búferes de memoria, es decir, trabajan con bytes y con índices de bytes.
  • A otras funciones se les proporciona la codificación del string, si bien es posible que asuman una codificación predeterminada si no se proporciona ninguna. Este es el caso dehtmlentities()y la mayoría de funciones de la extensiónmbstring.
  • Otras utilizan el localismo en uso (véasesetlocale()), pero operan byte a byte. Este es el caso destrcasecmp(),strtoupper()yucfirst(). Esto significa que sólo se pueden usar con codificaciones de un byte, siempre y cuando la codificación coincida con la del localismo. Por ejemplo,strtoupper("á")podría devolver"Á"si el localismo está correctamente establecido yáestá codificado con un único byte. Si está codificado en UTF-8, no se devolverá un resultado correcto, y el string resultante podría devolverse corrupto, en función del localismo en uso.
  • Por último, las funciones podrán también asumir que se utiliza una codificación en particular, usualmente UTF-8. Este es el caso de la mayoría de las funciones de la extensiónintly de la extensiónPCRE(en este último caso, sólo cuando se utiliza el modificadoru). Debido a su propósito especial, la funciónutf8_decode()asume una codificación UTF-8, mientras que la funciónutf8_encode()asume una codificación ISO-8859-1.

En resumen, para escribir programas de forma correcta usando Unicode hay que evitar cuidadosamente las funciones que puedan fallar y que muy probablemente corrompan los datos, y utilizar en su lugar las funciones que se comporten de forma correcta, generalmente las de las extensionesintlymbstring. Sin embargo, el uso de funciones que pueden manejar codificaciones Unicode es sólo el principio. No importa qué funciones incorpore el lenguaje; es primordial conocer la especificación Unicode. Por ejemplo, un programa que asuma que sólo hay mayúsculas y minúsculas estará haciendo una suposición errónea.



Numeric strings

A PHPstringis considered numeric if it can be interpreted as anintor afloat.

Formally as of PHP 8.0.0:

WHITESPACES      \s*
LNUM             [0-9]+
DNUM             ([0-9]*)[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM    (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
INT_NUM_STRING   {WHITESPACES} [+-]? {LNUM} {WHITESPACES}
FLOAT_NUM_STRING {WHITESPACES} [+-]? ({DNUM} | {EXPONENT_DNUM}) {WHITESPACES}
NUM_STRING       ({INT_NUM_STRING} | {FLOAT_NUM_STRING})

PHP also has a concept ofleadingnumeric strings. This is simply a string which starts like a numeric string followed by any characters.

Nota:

Any string that contains the letterE(case insensitive) bounded by numbers will be seen as a number expressed in scientific notation. This can produce unexpected results.

<?php
var_dump
("0D1"=="000");// false, "0D1" is not scientific notation
var_dump("0E1"=="000");// true, "0E1" is 0 * (10 ^ 1), or 0
var_dump("2E1"=="020");// true, "2E1" is 2 * (10 ^ 1), or 20
?>

Strings used in numeric contexts

When astringneeds to be evaluated as number (e.g. arithmetic operations,inttype declaration, etc.) the following steps are taken to determine the outcome:

  1. If thestringis numeric, resolve to anintif thestringis an integer numeric string and fits into the limits of theinttype limits (as defined byPHP_INT_MAX), otherwise resolve to afloat.
  2. If the context allows leading numeric strings and thestringis one, resolve to anintif the leading part of thestringis an integer numeric string and fits into the limits of theinttype limits (as defined byPHP_INT_MAX), otherwise resolve to afloat. Additionally an error of levelE_WARNINGis raised.
  3. Thestringis not numeric, throw aTypeError.

Behavior prior to PHP 8.0.0

Prior to PHP 8.0.0, astringwas considered numeric only if it hadleadingwhitespaces, if it hadtrailingwhitespaces then the string was considered to be leading numeric.

Prior to PHP 8.0.0, when a string was used in a numeric context it would perform the same steps as above with the following differences:

  • The usage of a leading numeric string would raise anE_NOTICEinstead of anE_WARNING.
  • If the string is not numeric, anE_WARNINGwas raised and the value0would be returned.
Prior to PHP 7.1.0, neitherE_NOTICEnorE_WARNINGwas raised.

<?php
$foo
=1+"10.5";// $foo is float (11.5)
$foo=1+"-1.3e3";// $foo is float (-1299)
$foo=1+"bob-1.3e3";// TypeError as of PHP 8.0.0, $foo is integer (1) previously
$foo=1+"bob3";// TypeError as of PHP 8.0.0, $foo is integer (1) previously
$foo=1+"10 Small Pigs";// $foo is integer (11) and an E_WARNING is raised in PHP 8.0.0, E_NOTICE previously
$foo=4+"10.2 Little Piggies";// $foo is float (14.2) and an E_WARNING is raised in PHP 8.0.0, E_NOTICE previously
$foo="10.0 pigs "+1;// $foo is float (11) and an E_WARNING is raised in PHP 8.0.0, E_NOTICE previously
$foo="10.0 pigs "+1.0;// $foo is float (11) and an E_WARNING is raised in PHP 8.0.0, E_NOTICE previously
?>


Arrays

Unarrayen PHP es en realidad un mapa ordenado. Un mapa es un tipo de datos que asociavaloresconclaves. Este tipo se optimiza para varios usos diferentes; se puede emplear como un array, lista (vector), tabla asociativa (tabla hash - una implementación de un mapa), diccionario, colección, pila, cola, y posiblemente más. Ya que los valores de unarraypueden ser otrosarrays, también son posibles árboles yarrays multidimensionales.

Una explicación sobre tales estructuras de datos está fuera del alcance de este manual, aunque se proporciona al menos un ejemplo de cada uno de ellos. Para más información, consulte la extensa literatura que existe sobre este amplio tema.

Sintaxis

Especificación conarray()

Unarraypuede ser creado con el constructor del lenguajearray(). Éste toma cualquier número de parejasclave=>valorcomo argumentos.

    array(
    clave  => valor,
    clave2 => valor2,
    clave3 => valor3,
    ...
    )

La coma después del último elemento del array es opcional, pudiéndose omitir. Esto normalmente se hace para arrays de una única línea, es decir, es preferiblearray(1, 2)quearray(1, 2, ). Por otra parte, para arrays multilínea, la coma final se usa frecuentemente, ya que permite una adición más sencilla de nuevos elementos al final.

A partir de PHP 5.4 también se puede usar la sintaxis de array corta, la cual reemplazaarray()con[].

Ejemplo #1 Un array simple

<?php
$array
= array(
"foo"=>"bar",
"bar"=>"foo",
);

// a partir de PHP 5.4
$array= [
"foo"=>"bar",
"bar"=>"foo",
];
?>

Laclavepuede ser unintegero unstring. Elvalorpuede ser de cualquier tipo.

Además, se darán los siguientes amoldamientos declave:

  • Strings que contiene un decimal válidointeger, a menos que el número esté precedido por un signo+, será amoldado al tipointeger. Por ejemplo, la llave"8"será en realidad almacenado como8. Por otro lado"08"no será moldeado, ya que no es un entero decimal válido.
  • Unfloats también será amoldado ainteger, lo que significa que la parte fraccionaria se elimina. P.ej., la clave8.7en realidad será almacenada como8.
  • Unbooleano son amoldados aintegers también, es decir, la clavetrueen realidad será almacenada como1y la clavefalsecomo0.
  • Unnullserá amoldado a un string vacío, es decir, la clavenullen realidad será almacenada como"".
  • Losarrays y losobjectsno puedenutilizarse como claves. Si se hace, dará lugar a una advertencia:Illegal offset type.

Si varios elementos en la declaración del array usan la misma clave, sólo se utilizará la última, siendo los demás sobrescritos.

Ejemplo #2 Ejemplo de amoldamiento de tipo y sobrescritura

<?php
$array
= array(
1=>"a",
"1"=>"b",
1.5=>"c",
true=>"d",
);
var_dump($array);
?>

El resultado del ejemplo sería:

array(1) {
  [1]=>
  string(1) "d"
}

Como todas las claves en el ejemplo anterior se convierten en1, los valores serán sobrescritos en cada nuevo elemento, por lo que el último valor asignado"d"es el único que queda.

Los arrays de PHP pueden contener clavesintegerystringal mismo tiempo ya que PHP no distingue entre arrays indexados y asociativos.

Ejemplo #3 Claves mixtasintegerystring

<?php
$array
= array(
"foo"=>"bar",
"bar"=>"foo",
100=> -100,
-
100=>100,
);
var_dump($array);
?>

El resultado del ejemplo sería:

array(4) {
  ["foo"]=>
  string(3) "bar"
  ["bar"]=>
  string(3) "foo"
  [100]=>
  int(-100)
  [-100]=>
  int(100)
}

Laclavees opcional. Si no se especifica, PHP usará el incremento de la clave de tipointegermayor utilizada anteriormente.

Ejemplo #4 Arrays indexados sin clave

<?php
$array
= array("foo","bar","hello","world");
var_dump($array);
?>

El resultado del ejemplo sería:

array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(5) "hello"
  [3]=>
  string(5) "world"
}

Es posible especificar la clave sólo para algunos elementos y excluir a los demás:

Ejemplo #5 Claves no en todos los elementos

<?php
$array
= array(
"a",
"b",
6=>"c",
"d",
);
var_dump($array);
?>

El resultado del ejemplo sería:

array(4) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [6]=>
  string(1) "c"
  [7]=>
  string(1) "d"
}

Como se puede ver, al último valor"d"se le asignó la clave7. Esto es debido a que la mayor clave integer anterior era6.

Acceso a elementos de array con la sintaxis de corchete

Los elementos de array se pueden acceder utilizando la sintaxisarray[key].

Ejemplo #6 Acceso a elementos de un array

<?php
$array
= array(
"foo"=>"bar",
42=>24,
"multi"=> array(
"dimensional"=> array(
"array"=>"foo"
)
)
);

var_dump($array["foo"]);
var_dump($array[42]);
var_dump($array["multi"]["dimensional"]["array"]);
?>

El resultado del ejemplo sería:

string(3) "bar"
int(24)
string(3) "foo"

Nota:

Tanto los corchetes como las llaves pueden ser utilizados de forma intercambiable para acceder a los elementos de un array (p.ej.:$array[42]y$array{42}tendrán el mismo resultado en el ejemplo anterior).

A partir de PHP 5.4 es posible hacer referencia al array del resultado de una llamada a una función o método directamente. Antes sólo era posible utilizando una variable temporal.

Desde PHP 5.5 es posible hacer referencia directa un elemento de un array literal.

Ejemplo #7 Hacer referencia al resultado array de funciones

<?php
functiongetArray() {
return array(
1,2,3);
}

// en PHP 5.4
$secondElement=getArray()[1];

// anteriormente
$tmp=getArray();
$secondElement=$tmp[1];

// o
list(,$secondElement) =getArray();
?>

Nota:

Intentar acceder a una clave de un array que no se ha definido es lo mismo que el acceder a cualquier otra variable no definida: se emitirá un mensaje de error de nivelE_NOTICE, y el resultado seránull.

Nota:

Array que dereferencia un valor escalar que no es unstringsilenciosamente arrojanull, es decir, sin emitir un mensaje de error.

Creación/modificación con la sintaxis de corchete

Unarrayexistente puede ser modificado estableciendo explícitamente valores en él.

Esto se realiza asignando valores alarray, especificando la clave entre corchetes. Esta también se puede omitir, resultando en un par de corchetes vacíos ([]).

    $arr[clave] = valor;
    $arr[] = valor;
    // clave puede ser un integer o un string
    // valor puede ser cualquier valor de cualquier tipo

Si$arraún no existe, se creará, siendo también esta forma una alternativa de crear unarray. Sin embargo, se desaconsejada esta práctica porque que si$arrya contiene algún valor (p.ej. unstringde una variable de petición), este estará en su lugar y[]puede significar realmente eloperador de acceso a strings. Siempre es mejor inicializar variables mediante una asignación directa.

Nota:A partir de PHP 7.1.0, la aplicación del operador de índice vacío en un string lanza un fatal error. Antes, el string se convertía silenciosamente en un array.

Para cambiar un valor determinado se debe asignar un nuevo valor a ese elemento empleando su clave. Para quitar una pareja clave/valor, se debe llamar a la funciónunset()con éste.

<?php
$arr
= array(5=>1,12=>2);

$arr[] =56;// Esto es lo mismo que $arr[13] = 56;
// en este punto de el script

$arr["x"] =42;// Esto agrega un nuevo elemento a
// el array con la clave "x"

unset($arr[5]);// Esto elimina el elemento del array

unset($arr);// Esto elimina el array completo
?>

Nota:

Como se mencionó anteriormente, si no se especifica una clave, se toma el máximo de los índicesintegerexistentes, y la nueva clave será ese valor máximo más 1 (aunque al menos 0). Si todavía no existen índicesinteger, la clave será0(cero).

Tenga en cuenta que la clave integer máxima utilizada para ésteno es necesario que actualmente exista en elarray. Ésta sólo debe haber existido en elarrayen algún momento desde la última vez que elarrayfué re-indexado. El siguiente ejemplo ilustra este comportamiento:

<?php
// Crear un array simple.
$array= array(1,2,3,4,5);
print_r($array);

// Ahora elimina cada elemento, pero deja el mismo array intacto:
foreach ($arrayas$i=>$value) {
unset(
$array[$i]);
}
print_r($array);

// Agregar un elemento (note que la nueva clave es 5, en lugar de 0).
$array[] =6;
print_r($array);

// Re-indexar:
$array=array_values($array);
$array[] =7;
print_r($array);
?>

El resultado del ejemplo sería:

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)
Array
(
)
Array
(
    [5] => 6
)
Array
(
    [0] => 6
    [1] => 7
)

Funciones útiles

Hay un buen número de funciones útiles para trabajar con arrays. Véase la secciónfunciones de array.

Nota:

La funciónunset()permite remover claves de unarray. Tenga en cuenta que el arraynoes re-indexado. Si se desea un verdadero comportamiento "eliminar y desplazar", elarraypuede ser re-indexado usando la funciónarray_values().

<?php
$a
= array(1=>'uno',2=>'dos',3=>'tres');
unset(
$a[2]);
/* producirá un array que se ha definido como
$a = array(1 => 'uno', 3 => 'tres');
y NO
$a = array(1 => 'uno', 2 =>'tres');
*/

$b=array_values($a);
// Ahora $b es array(0 => 'uno', 1 =>'tres')
?>

La estructura de controlforeachexiste específicamente paraarrays. Ésta provee una manera fácil de recorrer unarray.

Recomendaciones sobre arrays y cosas a evitar

¿Por qué es incorrecto$foo[bar]?

Siempre deben usarse comillas alrededor de un índice de array tipo string literal. Por ejemplo,$foo['bar']es correcto, mientras que$foo[bar]no lo es. ¿Pero por qué? Es común encontrar este tipo de sintaxis en scripts viejos:

<?php
$foo
[bar] ='enemy';
echo
$foo[bar];
// etc
?>

Esto está mal, pero funciona. La razón es que este código tiene una constante indefinida (bar) en lugar de unstring('bar'- observe las comillas). Funciona porque PHP automáticamente convierte unstring puro(unstringsin comillas que no corresponde con ningún símbolo conocido) en unstringque contiene elstringpuro. Por ejemplo, si no se ha definido una constante llamadabar, entonces PHP reemplazará su valor por elstring'bar'y usará éste último.

Advertencia

La alternativa de tratar una constante indefinida como string vacío está obsoleto a partir de PHP 7.2.0, y emite un error de nivelE_WARNING. Anteriormente, un error de nivelE_NOTICEera emitido.

Nota:Esto no quiere decir quesiemprehaya que usar comillas en la clave. No use comillas con claves que seanconstantesovariables, ya que en tal caso PHP no podrá interpretar sus valores.

<?php
error_reporting
(E_ALL);
ini_set('display_errors',true);
ini_set('html_errors',false);
// Array simple:
$array= array(1,2);
$count=count($array);
for (
$i=0;$i<$count;$i++) {
echo
"\nRevisando$i: \n";
echo
"Mal: ".$array['$i'] ."\n";
echo
"Bien: ".$array[$i] ."\n";
echo
"Mal:{$array['$i']}\n";
echo
"Bien:{$array[$i]}\n";
}
?>

El resultado del ejemplo sería:

Revisando 0:
Notice: Undefined index:  $i in /path/to/script.html on line 9
Mal:
Bien: 1
Notice: Undefined index:  $i in /path/to/script.html on line 11
Mal:
Bien: 1

Revisando 1:
Notice: Undefined index:  $i in /path/to/script.html on line 9
Mal:
Bien: 2
Notice: Undefined index:  $i in /path/to/script.html on line 11
Mal:
Bien: 2

Más ejemplos para demostrar este comportamiento:

<?php
// Mostrar todos los errores
error_reporting(E_ALL);

$arr= array('fruit'=>'apple','veggie'=>'carrot');

// Correcto
print$arr['fruit'];// apple
print$arr['veggie'];// carrot

// Incorrecto. Esto funciona pero también genera un error de PHP de
// nivel E_NOTICE ya que no hay definida una constante llamada fruit
//
// Notice: Use of undefined constant fruit - assumed 'fruit' in...
print$arr[fruit];// apple

// Esto define una constante para demostrar lo que pasa. El valor 'veggie'
// es asignado a una constante llamada fruit.
define('fruit','veggie');

// Note la diferencia ahora
print$arr['fruit'];// apple
print$arr[fruit];// carrot

// Lo siguiente está bien ya que se encuentra al interior de una cadena. Las constantes no son procesadas al
// interior de cadenas, así que no se produce un error E_NOTICE aquí
print"Hello$arr[fruit]";// Hello apple

// Con una excepción, los corchetes que rodean las matrices al
// interior de cadenas permiten el uso de constantes
print"Hello{$arr[fruit]}";// Hello carrot
print"Hello{$arr['fruit']}";// Hello apple

// Esto no funciona, resulta en un error de intérprete como:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// Esto por supuesto se aplica también al uso de superglobales en cadenas
print"Hello$arr['fruit']";
print
"Hello$_GET['foo']";

// La concatenación es otra opción
print"Hello ".$arr['fruit'];// Hello apple
?>

Cuando se habilitaerror_reportingpara mostrar errores de nivelE_NOTICE(como por ejemplo definiendo el valorE_ALL), este tipo de usos serán inmediatamente visibles. Por omisión,error_reportingse encuentra configurado para no mostrarlos.

Tal y como se indica en la sección desintaxis, lo que existe entre los corchetes cuadrados ('[' y ']') debe ser una expresión. Esto quiere decir que código como el siguiente funciona:

<?php
echo$arr[somefunc($bar)];
?>

Este es un ejemplo del uso de un valor devuelto por una función como índice del array. PHP también conoce las constantes:

<?php
$error_descriptions
[E_ERROR] ="Un error fatal ha ocurrido";
$error_descriptions[E_WARNING] ="PHP produjo una advertencia";
$error_descriptions[E_NOTICE] ="Esta es una noticia informal";
?>

Note queE_ERRORes también un identificador válido, asi comobaren el primer ejemplo. Pero el último ejemplo es equivalente a escribir:

<?php
$error_descriptions
[1] ="Un error fatal ha ocurrido";
$error_descriptions[2] ="PHP produjo una advertencia";
$error_descriptions[8] ="Esta es una noticia informal";
?>

ya queE_ERRORes igual a1, etc.

¿Entonces porqué está mal?

En algún momento en el futuro, puede que el equipo de PHP quiera usar otra constante o palabra clave, o una constante proveniente de otro código puede interferir. Por ejemplo, en este momento no puede usar las palabrasemptyydefaultde esta forma, ya que sonpalabras clave reservadas.

Nota:Reiterando, al interior de un valorstringentre comillas dobles, es válido no rodear los índices de array con comillas, así que"$foo[bar]"es válido. Consulte los ejemplos anteriores para más detalles sobre el porqué, así como la sección sobreprocesamiento de variables en cadenas.

Conversión a array

Para cualquiera de los tiposinteger,float,string,booleanyresource, convertir un valor a unarrayresulta en un array con un solo elemento, con índice 0, y el valor del escalar que fue convertido. En otras palabras,(array)$scalarValuees exactamente lo mismo quearray($scalarValue).

Si convierte unobjecta unarray, el resultado es unarraycuyos elementos son las propiedades delobject. Las claves son los nombres de las variables miembro, con algunas excepciones notables: las variables privadas tienen el nombre de la clase al comienzo del nombre de la variable; las variables protegidas tienen un caracter '*' al comienzo del nombre de la variable. Estos valores adicionados al inicio tienen bytesNULa los lados. Laspropiedades tipificadasno inicializadas se descartan silenciosamente.

<?php

classA{
private
$A;// Este campo se convertirá en '\0A\0A'
}

class
BextendsA{
private
$A;// Este campo se convertirá en '\0B\0A'
public$AA;// Este campo se convertirá en 'AA'
}

var_dump((array) newB());
?>

En el ejemplo anterior parecerá que se tienen dos claves llamadas 'AA', aunque en realidad una de ellas se llama '\0A\0A'.

Si convierte un valornullaarray, obtiene unarrayvacío.

Comparación

Es posible comparar arrays con la funciónarray_diff()y medianteoperadores de arrays.

Ejemplos

El tipo array en PHP es bastante versátil. Aquí hay algunos ejempos:

<?php
// Esto:
$a= array('color'=>'red',
'taste'=>'sweet',
'shape'=>'round',
'name'=>'apple',
4// la clave será 0
);

$b= array('a','b','c');

// . . .es completamente equivalente a
$a= array();
$a['color'] ='red';
$a['taste'] ='sweet';
$a['shape'] ='round';
$a['name'] ='apple';
$a[] =4;// la clave será 0

$b= array();
$b[] ='a';
$b[] ='b';
$b[] ='c';

// Después de que se ejecute el código, $a será el array
// array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
// 'name' => 'apple', 0 => 4), y $b será el array
// array(0 => 'a', 1 => 'b', 2 => 'c'), o simplemente array('a', 'b', 'c').
?>

Ejemplo #8 Uso de array()

<?php
// Array como mapa de propiedades
$map= array('version'=>4,
'OS'=>'Linux',
'lang'=>'english',
'short_tags'=>true
);

// Keys estrictamente numéricas
$array= array(7,
8,
0,
156,
-
10
);
// esto es lo mismo que array(0 => 7, 1 => 8, ...)

$switching= array(10,// key = 0
5=>6,
3=>7,
'a'=>4,
11,// key = 6 (el índice entero máximo era 5)
'8'=>2,// key = 8 (integer!)
'02'=>77,// key = '02'
0=>12// el valor 10 será reemplazado por 12
);

// array vacío
$empty= array();
?>

Ejemplo #9 Colección

<?php
$colors
= array('rojo','azul','verde','amarillo');

foreach (
$colorsas$color) {
echo
"¿Le gusta el$color?\n";
}

?>

El resultado del ejemplo sería:

¿Le gusta el rojo?
¿Le gusta el azul?
¿Le gusta el verde?
¿Le gusta el amarillo?

Modificar los valores delarraydirectamente es posible pasándolos por referencia.

Ejemplo #10 Cambiando elemento en el bucle

<?php
foreach ($colorsas &$color) {
$color=strtoupper($color);
}
unset(
$color);/* se asegura de que escrituras subsiguientes a $color
no modifiquen el último elemento del arrays */

print_r($colors);
?>

El resultado del ejemplo sería:

Array
(
    [0] => ROJO
    [1] => AZUL
    [2] => VERDE
    [3] => AMARILLO
)

Este ejemplo crea un array con base uno.

Ejemplo #11 Índice con base 1

<?php
$firstquarter
= array(1=>'Enero','Febrero','Marzo');
print_r($firstquarter);
?>

El resultado del ejemplo sería:

Array
(
    [1] => 'Enero'
    [2] => 'Febrero'
    [3] => 'Marzo'
)

Ejemplo #12 Llenado de un array

<?php
// llenar un array con todos los ítems de un directorio
$handle=opendir('.');
while (
false!== ($file=readdir($handle))) {
$files[] =$file;
}
closedir($handle);
?>

LosArrays son ordenados. El orden puede ser modificado usando varias funciones de ordenado. Vea la sección sobrefunciones de arrayspara más información. La funcióncount()puede ser usada para contar el número de elementos en unarray.

Ejemplo #13 Ordenado de un array

<?php
sort
($files);
print_r($files);
?>

Dado que el valor de unarraypuede ser cualquier cosa, también puede ser otroarray. De esta forma es posible creararrays recursivas y multi-dimensionales.

Ejemplo #14 Arrays recursivos y multi-dimensionales

<?php
$fruits
= array ("fruits"=> array ("a"=>"orange",
"b"=>"banana",
"c"=>"apple"
),
"numbers"=> array (1,
2,
3,
4,
5,
6
),
"holes"=> array ("first",
5=>"second",
"third"
)
);

// Algunos ejemplos que hacen referencia a los valores del array anterior
echo$fruits["holes"][5];// prints "second"
echo$fruits["fruits"]["a"];// prints "orange"
unset($fruits["holes"][0]);// remove "first"

// Crear una nueva array multi-dimensional
$juices["apple"]["green"] ="good";
?>

La asignación dearrays siempre involucra la copia de valores. Use eloperador de referenciapara copiar unarraypor referencia.

<?php
$arr1
= array(2,3);
$arr2=$arr1;
$arr2[] =4;// $arr2 ha cambiado,
// $arr1 sigue siendo array(2, 3)

$arr3= &$arr1;
$arr3[] =4;// ahora $arr1 y $arr3 son iguales
?>


Iterables

Iterablees un seudotipo introducido en PHP 7.1. Acepta cualquierarrayu objeto que implemente la interfazTraversable. Estos dos tipos se recorren conforeachy se pueden emplear conyield fromdentro de ungenerador.

Empleo de iterables

Iterable se puede usar como tipo de parámetro para indicar que una función requiere un conjunto de valores, pero que no importa la forma del dicho conjunto ya que se utiizará conforeach. Si un valor no es un array o una instancia deTraversable, se lanzará unTypeError.

Ejemplo #1 Ejemplo de de tipo de parámetro iterable

<?php

functionfoo(iterable $iterable) {
foreach (
$iterableas$valor) {
// ...
}
}

?>

Los parámetros declarados como iterable pueden usarnullo un array como valor predeterminado.

Ejemplo #2 Ejemplo de valor predeterminado de un parámetro iterable

<?php

functionfoo(iterable $iterable= []) {
// ...
}

?>

Iterable se puede usar como tipo de retorno para indicar que una función devolverá un valor iterable. Si el valor devuelto no es un array o una instancia deTraversable, se lanzará unTypeError.

Ejemplo #3 Ejemplo de tipo de retorno iterable

<?php

functionbar():iterable{
return [
1,2,3];
}

?>

Las funciones que declaren su tipo de retorno como también pueden sergeneradores.

Ejemplo #4 Ejemplo de tipo de retorno de generadro iterable

<?php

functiongen():iterable{
yield
1;
yield
2;
yield
3;
}

?>

Varianza del tipo iterable

Las clases que extiendan/implementen podrían ampliar los métodos usandoarrayoTraversablecomo tipos de parámetro aiterableo reducir los tipos de retorno deiterableaarrayoTraversable.

Ejemplo #5 Ejemplo de varianza del tipo iterable

<?php

interfaceEjemplo{
public function
method(array$array):iterable;
}

class
ImplementaciónDeEjemploimplementsEjemplo{
public function
method(iterable $iterable): array {
// Parámetro ampliado y tipo de retorno reducido.
}
}

?>



Objetos

Inicialización de objetos

Para crear un nuevoobject, utilice la sentencianewpara instanciar una clase:

<?php
classfoo
{
function
hacer_algo()
{
echo
"Haciendo algo.";
}
}

$bar= newfoo;
$bar->hacer_algo();
?>

Para una descripción completa, véase el capítuloClases y objetos.

Conversión a un objeto

Si unobjectse convierte en unobject, éste no se modifica. Si un valor de cualquier otro tipo se convierte en unobject, se crea una nueva instancia de la clasestdClassincorporada. Si el valor esnull, la nueva instancia estará vacía. Unarrayse convierte en unobjectcon las propiedades nombradas como claves y los valores correspondientes, con la excepción de las claves numéricas, las cuales serán inaccesibles a menos que sean recorridas.

<?php
$obj
= (object) array('1'=>'foo');
var_dump(isset($obj->{'1'}));// muestra 'bool(false)'
var_dump(key($obj));// muestra 'int(1)'
?>

Para cualquier otro valor, una variable miembro llamadascalarcontendrá el valor.

<?php
$obj
= (object)'ciao';
echo
$obj->scalar;// muestra 'ciao'
?>


Recursos

Un valor tiporesourcees una variable especial, que contiene una referencia a un recurso externo. Los recursos son creados y usados por funciones especiales. Vea elapéndicepara un listado de todas estas funciones y los tiposresourcecorrespondientes.

Vea también la funciónget_resource_type().

Conversión a recurso

Dado que las variablesresourcecontienen gestores especiales a archivos abiertos, conexiones con bases de datos, áreas de pintura de imágenes y cosas por el estilo, la conversión a tiporesourcecarece de sentido.

Liberación de recursos

Gracias al sistema de conteo de referencias introducido con el Motor Zend, un recurso que ya no es referenciado es detectado automáticamente, y es liberado por el recolector de basura. Por esta razón, rara vez se necesita liberar la memoria manualmente.

Nota:Los enlaces persistentes con bases de datos son una excepción a esta regla. Ellosnoson destruidos por el recolector de basura. Vea también la sección sobreconexiones persistentespara más información.



NULO

El valor especialnullrepresenta una variable sin valor.nulles el único valor posible del tiponull.

Una variable es consideradanullsi:

  • se le ha asignado la constantenull.

  • no se le ha asignado un valor todavía.

  • se ha destruido conunset().

Sintaxis

No hay más que un valor de tiponull, y es la constantenullinsensible a mayúsculas/minúsculas.

<?php
$var
=NULL;
?>

Véase también las funcionesis_null()yunset().

La conversión anull

Advertencia

Esta característica ha sido declaradaOBSOLETAa partir de PHP 7.2.0. Su uso está totalmente desaconsejado.

Convertir una variable anullusando(unset) $varnoeliminará la variable ni destruirá su valor. Sólo retornará un valornull.



Llamadas de retorno (Callbacks / Callables)

Las llamadas de retorno, o retrollamadas, se pueden indicar con la declaración de tipocallablea partir de PHP 5.4. Esta documentación utilizó la información del tipocallbackcon el mismo propósito.

Algunas funciones comocall_user_func()ousort()aceptan como parámetro funciones de llamada de retorno definidas por el usuario. Las funciones de llamadas de retorno no sólo pueden ser funciones simples, sino también métodos de unobject, incluyendo métodos de clase estáticos.

Pasar una función de llamada de retorno

Una función de PHP se pasa por su nombre como unstring. Se puede utilizar cualquier función nativa o definida por el usuario, exceptuando contrucciones del lenguaje, tales como:array(),echo,empty(),eval(),exit(),isset(),list(),printounset().

Un método de unobjectinstanciado se pasa como unarrayque contiene unobjecten el índice 0 y el nombre del método en el índice 1. Está permitido el acceso a métodos protegidos y privados desde dentro de una clase.

Los métodos de clase estáticos también se pueden pasar sin instanciar unobjectde dicha clase, pasando el nombre de la clase en lugar de unobjecten el índice 0. A partir de PHP 5.2.3, también es posible pasar'NombreDeClase::nombreDeMetodo'.

A parte de las funciones comunes definidas por el usuario, lasfunciones anónimastambién se pueden pasar a un parámetro de llamada de retorno.

Ejemplo #1 Ejemplos de funciones de llamadas de retorno

<?php

// Un ejemplo de función de llamada de retorno
functionmi_función_de_llamada_de_retorno() {
echo
'¡hola mundo!';
}

// Un ejemplo de método de llamada de retorno
classMiClase{
static function
miMétodoDeLlamadaDeRetorno() {
echo
'¡Hola Mundo!';
}
}

// Tipo 1: Llamada de retorno simple
call_user_func('mi_función_de_llamada_de_retorno');

// Tipo 2: Llamada a un método de clase estático
call_user_func(array('MiClase','miMétodoDeLlamadaDeRetorno'));

// Tipo 3: Llamada al método de un objeto
$obj= newMiClase();
call_user_func(array($obj,'miMétodoDeLlamadaDeRetorno'));

// Tipo 4: Llamada a un método de clase estático (A partir de PHP 5.2.3)
call_user_func('MiClase::miMétodoDeLlamadaDeRetorno');

// Tipo 5: Llamada a un método de clase estático relativo (A partir de PHP 5.3.0)
classA{
public static function
quién() {
echo
"A\n";
}
}

class
BextendsA{
public static function
quién() {
echo
"B\n";
}
}

call_user_func(array('B','parent::quién'));// A

// Tipe 6: Los objetos que implementan __invoke se pueden emplear como retrollamadas (desde PHP 5.3)
classC{
public function
__invoke($nombre) {
echo
'Hola ',$nombre,"\n";
}
}

$c= newC();
call_user_func($c,'PHP!');
?>

Ejemplo #2 Ejemplo de retrollamada utilizando un cierre

<?php
// Nuestro cierre
$doble= function($a) {
return
$a*2;
};

// Este es nuestro rango de números
$números=range(1,5);

// Usar el cierre como llamada de retorno para
// doblar el valor de cada elemento de nuestro
// rango
$números_nuevos=array_map($doble,$números);

print
implode(' ',$números_nuevos);
?>

El resultado del ejemplo sería:

2 4 6 8 10

Nota:

Las funciones de retorno de llamada que se registran con funciones comocall_user_func()ycall_user_func_array()no se llamarán si se produce una excepción en la función de retorno previa.



Declaraciones de tipo

Las declaraciones de tipo pueden ser añadidas a los argumentos de función, valores de retorno y desde PHP 7.4.0, propiedades de clase. Éstas declaraciones aseguran que el valor es del tipo especificado en el momento de la llamada, de no ser así se lanzará una excepción de tipoTypeError.

Nota:

Cuando se sobreescribe el método de un padre, el método hijo debe coincidir con cualquier tipo de declaración de retorno del padre. Si el padre no tiene definida un tipo de retorno, entonces el método hijo puede realizarla.

Tipos simples

TipoDescripciónVersión
Nombre de la Clase/InterfazEl valor debe ser una instancia de la clase o de la interfaz. 
selfEl valor debe ser unainstanceofde la misma clase que aquella en la que se utiliza la declaración de tipo. Solamente se puede usar en clases. 
parentEl valor debe ser unainstanceofdel padre de la clase en la que se usa la declaración de tipo. Solo se puede usar en clases. 
arrayEl valor debe ser unarray. 
callableEl valor debe ser uncallableválido. No puede ser usado como una declaración de tipo de propiedad de clase. 
boolEl valor debe ser un valor booleano. 
floatEl valor debe ser un número de coma flotante. 
intEl valor debe ser un número entero. 
stringEl valor debe ser unstring. 
iterableEl valor debe ser unarrayo unainstanceofde la claseTraversable.PHP 7.1.0
objectEl valor debe ser unobjeto.PHP 7.2.0
mixedEl valor puede ser cualquier valor.PHP 8.0.0
Advertencia

No se admiten los alias para los tipos escalares anteriores. En su lugar, se tratan como nombres de clase o interfaz. Por ejemplo, usarbooleancomo declaración de tipo requerirá que el valor sea unainstanceofde clase o interfazboolean, en lugar de tipobool:

<?php
functiontest(boolean $parametro) {}
test(true);
?>

Output of the above example in PHP 8:

Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
Stack trace:
#0 -(3): test(true)
#1 {main}
  thrown in - on line 2

mixed

mixedes equivalente aunion typeobject|resource|array|string|int|float|bool|null. Disponible a partir de PHP 8.0.0.

Ejemplos

Ejemplo #1 Declaración de tipo de clase básica

<?php
classC{}
class
DextendsC{}

// Esta clase no extiende de C.
classE{}

function
f(C $c) {
echo
get_class($c)."\n";
}

f(newC);
f(newD);
f(newE);
?>

Output of the above example in PHP 8:

C
D

Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
  thrown in - on line 8

Ejemplo #2 Declaración de tipo de interfaz básica

<?php
interfaceI{ public functionf(); }
class
CimplementsI{ public functionf() {} }

// Esta clase no implementa I.
classE{}

function
f(I $i) {
echo
get_class($i)."\n";
}

f(newC);
f(newE);
?>

Output of the above example in PHP 8:

C

Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
  thrown in - on line 8

Ejemplo #3 Declaración de tipo de retorno básica

<?php
functionsuma($a,$b):float{
return
$a+$b;
}

// Se devolverá un valor float.
var_dump(suma(1,2));
?>

El resultado del ejemplo sería:

float(3)

Ejemplo #4 Retornando un objeto

<?php
classC{}

function
getC():C{
return new
C;
}

var_dump(getC());
?>

El resultado del ejemplo sería:

object(C)#1 (0) {
}

Tipo Nullable

A partir de PHP 7.1.0, las declaraciones de tipo pueden ser marcadas como nullable anteponiendo un interrogante(?) en el nombre de tipo. Esto conlleva a que el valor puede ser del tipo específico onull.

Ejemplo #5 Declaración de tipo de argumento Nullable

<?php
classC{}

function
f(?C $c) {
var_dump($c);
}

f(newC);
f(null);
?>

El resultado del ejemplo sería:

object(C)#1 (0) {
}
NULL

Ejemplo #6 Declaración de tipo de retorno Nullable

<?php
functionget_item(): ?string{
if (isset(
$_GET['item'])) {
return
$_GET['item'];
} else {
return
null;
}
}
?>

Nota:

Es posible lograr argumentos anulables haciendonullel valor por defecto. Esto no se recomienda ya que se rompe durante la herencia.

Ejemplo #7 Forma antigua de hacer argumentos nullable por defecto

<?php
classC{}

function
f(C $c=null) {
var_dump($c);
}

f(newC);
f(null);
?>

El resultado del ejemplo sería:

object(C)#1 (0) {
}
NULL

Tipos compuestos

Es posible combinar tipos simples en tipos compuestos. PHP permite combinar tipos de las siguientes maneras:

  • Union de tipos simples. A partir de 8.0.0.
  • Intersección de tipos de clases (interfaces y nombres de clase). A partir de PHP 8.1.0.
Precaución

No es posible combinar tipos intersección con tipos unión.

Tipos unión

Una declaración de tipo de unión acepta valores de múltiples tipos simples diferentes, en lugar de uno solo. Los tipos de unión se especifican mediante la sintaxisT1|T2|.... Los tipos de unión están disponibles a partir de PHP 8.0.0.

Tipos unión Nullable

El tiponullse admite como parte de las uniones, de modo queT1|T2|nullse puede usar para crear una unión nullable. La notación?Texistente se considera una forma abreviada del caso común deT|null.

Precaución

nullno puede ser usado como tipo standalone.

false pseudo-type

Thefalseliteral type is supported as part of unions, and is included as for historical reasons many internal functions returnfalseinstead ofnullfor failures. A classic example of such a function isstrpos().

Precaución

falseno se puede usar como tipo independiente (incluido tipo independiente nullable). Por este motivofalse,false|nully?falseno están permitidos.

Precaución

El literaltruenoexiste.

Tipos Intersección

Una declaración de tipo de Intersección acepta valores que satisfacen múltiples declaraciones de tipo de clase, en lugar de una sola. Los tipos Intersección se especifican usando la sintaxisT1&T2&...Los tipos Intersección están disponibles a partir de PHP 8.1.0.

Tipos duplicados y redundantes

Para detectar errores simples en declaraciones de tipos compuestos, los tipos redundantes que se puedan detectar sin realizar la carga de clase dará como resultado un error en tiempo de compilación. Esto incluye:

  • Solamente podrá resolverse un mismo tipo una vez. Los tipos comoint|string|INToCountable&Traversable&COUNTABLEdarán como resultado un error.
  • Usar el tipomixeddará como resultado un error.
  • Para los tipos Unión:
    • Si se usa el tipobool,falseno puede ser usado adicionalmente.
    • Si se usa el tipoobject, los tipos para clase no pueden ser usados adicionalmente.
    • Si se usa el tipoiterable,arrayyTraversableno podrán ser usados adicionalmente.
  • Para los tipos Intersección:
    • El uso de un tipo que no sea un tipo de clase dará como resultado un error.
    • El uso deself,parent, ostaticresultará en error.

Nota:Esto no garantiza que el tipo sea "mínimo", porque hacerlo requeriría cargar todos los tipos de clase usados.

Por ejemplo, siAyBson alias de clase, entoncesA|Bsigue siendo un tipo de unión legal, aunque podría reducirse aAoB. De manera similar, si la claseB extends A {}, entoncesA|Bes también un tipo de unión legal, aunque podría reducirse a soloA.

<?php
functionfoo():int|INT{}// No permitido
functionfoo():bool|false{}// No permitido
functionfoo():int&Traversable{}// No permitido
functionfoo():self&Traversable{}// No permitido

useAasB;
function
foo():A|B{}// No permitido ("use" es parte de la resolución del nombre)
functionfoo():A&B{}// No permitido ("use" es parte de la resolución del nombre)

class_alias('X','Y');
function
foo():X|Y{}// Permitido (La redundancia solo se detecta en tiempo de ejecución)
functionfoo():X&Y{}// Permitido (La redundancia solo se detecta en tiempo de ejecución)
?>

Tipos de solo lectura

void

voides un tipo de retorno que indica que la función no devuelve un valor. Por lo tanto, no puede ser parte de una declaración de tipo de unión. Disponible a partir de PHP 7.1.0.

Nota:

Queda obsoleto el retorno por referencia desde una funcionvoida partir de PHP 8.1.0, debido a que dicha función es contradictoria. Previamente emitía el siguienteE_NOTICEcuando se llamaba:Only variable references should be returned by reference

<?php
function &test():void{}
?>

never

neveres un tipo de retorno que indica que la función no retorna. Esto significa que llama aexit(), lanza una excepción o es un ciclo infinito. Por lo tanto, no puede ser parte de una declaración de tipo de unión. Disponible a partir de PHP 8.1.0.

neveres, en el lenguaje de la teoría de tipos, el tipo inferior. Lo que significa que es el subtipo de cualquier otro tipo y puede reemplazar cualquier otro tipo de retorno durante la herencia.

static

El valor debe ser una instancia de la misma clase en la que se llama al método. Disponible a partir de PHP 8.0.0.

Tipificación estricto

Por defecto, PHP forzará los valores del tipo incorrecto en la declaración de tipo escalar esperada si es posible. Por ejemplo, una función a la que se le da unintpara un parámetro que espera unastringobtendrá una variable de tipostring.

Es posible habilitar el modo estricto por archivo. En modo estricto, solo se aceptará un valor que corresponda exactamente a la declaración de tipo. De lo contrario, se lanzará unTypeError. La única excepción a esta regla es que un valorintpasará una declaración de tipofloat.

Advertencia

Las llamadas a funciones desde funciones internas no se verán afectadas por la declaración destrict_types.

Para habilitar el modo estricto, se usa el constructordeclarecon la declaraciónstrict_types=1.

Nota:

El tipado estricto se aplica a las llamadas de función realizadas desde dentro del archivo con el tipado estricto habilitado, no a las funciones declaradas de ese archivo. Si un archivo sinstrict_typesactivado realiza una llamada a una función que se definió en un archivo constrict_typesactivado, la preferencia será respetada (escritura coercitiva) y se forzará el valor.

Nota:

La tipificación estricta solo está definida para declaraciones de tipos escalares.

Ejemplo #8 Tipificación estricta para los valores de los argumentos

<?php
declare(strict_types=1);

function
suma(int $a,int $b) {
return
$a+$b;
}

var_dump(suma(1,2));
var_dump(suma(1.5,2.5));
?>

Output of the above example in PHP 8:

int(3)

Fatal error: Uncaught TypeError: suma(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
  thrown in - on line 4

Ejemplo #9 Tipificación coercitiva para valores de los argumentos

<?php
functionsuma(int $a,int $b) {
return
$a+$b;
}

var_dump(suma(1,2));

// Estos serán forzados a números enteros: ¡observe el resultado a continuación!
var_dump(suma(1.5,2.5));
?>

El resultado del ejemplo sería:

int(3)
int(3)

Ejemplo #10 Tipificación estricta para valores de retorno

<?php
declare(strict_types=1);

function
suma($a,$b):int{
return
$a+$b;
}

var_dump(suma(1,2));
var_dump(suma(1,2.5));
?>

El resultado del ejemplo sería:

int(3)

Fatal error: Uncaught TypeError: suma(): Return value must be of type int, float returned in -:5
Stack trace:
#0 -(9): suma(1, 2.5)
#1 {main}
  thrown in - on line 5

Tipificación coercitiva con tipos Unión

Cuandostrict_typesno está activado, las declaraciones de tipo escalar están sujetas a coerciones de tipo limitadas. Si el tipo exacto del valor no es parte de la unión, entonces el tipo de destino se elige en el siguiente orden de preferencia:

  1. int
  2. float
  3. string
  4. bool
Si el tipo existe en la unión, y el valor se puede forzar al tipo bajo la semántica de verificación de tipo existente de PHP, entonces se elige el tipo. De lo contrario, se prueba el siguiente tipo.

Precaución

Como excepción, si el valor es una cadena y tanto int como float son parte de la unión, el tipo preferido está determinado por la semántica de "cadena numérica" ​​existente. Por ejemplo, para"42"se eligeint, mientras que para"42.0"se eligefloat.

Nota:

Los tipos que no forman parte de la lista de preferencias anterior no son objetivos elegibles para la coerción implícita. En particular, no ocurre ninguna coerción implícita para los tiposnullyfalse.

Ejemplo #11 Ejemplo de tipos siendo forzados a formar parte del tipo Unión

<?php
// int|string
42-->42// tipo exacto
"42"-->"42"// tipo exacto
newObjectWithToString-->"Resultado de __toString()"
// object nunca compatible con int, se resuelve como string
42.0-->42// float compatible con int
42.1-->42// float compatible con int
1e100-->"1.0E+100"// float demasiado largo para tipo int, se resuelve como string
INF-->"INF"// float demasiado largo para tipo int, se resuelve como string
true-->1// bool compatible con int
[] -->TypeError// array no compatible con int o string

// int|float|bool
"45"-->45// string numérico int
"45.0"-->45.0// string numérico float

"45X"-->true// no es string numérico, se resuelve como bool
""-->false// no es string numérico, se resuelve como bool
"X"-->true// no es string numérico, se resuelve como bool
[] -->TypeError// array no compatible con int, float or bool
?>

Misc

Ejemplo #12 Tipificación de parámetros pasados por referencia

Los tipos declarados de parámetros pasados por referencia se verifican en la entrada de la función, pero no cuando la función devuelve el retorno, por lo que después de que la función haya devuelvo el retorno, el tipo de argumento puede haber cambiado.

<?php
functionarray_baz(array &$param)
{
$param=1;
}
$var= [];
array_baz($var);
var_dump($var);
array_baz($var);
?>

Output of the above example in PHP 8:

int(1)

Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
Stack trace:
#0 -(9): array_baz(1)
#1 {main}
  thrown in - on line 2

Ejemplo #13 CapturandoTypeError

<?php
declare(strict_types=1);

function
suma(int $a,int $b) {
return
$a+$b;
}

try {
var_dump(suma(1,2));
var_dump(suma(1.5,2.5));
} catch (
TypeError $e) {
echo
'Error: ',$e->getMessage();
}
?>

Output of the above example in PHP 8:

int(3)
Error: suma(): Argument #1 ($a) must be of type int, float given, called in - on line 10


Manipulación de tipos

PHP no requiere (ni soporta) la definición explicita de tipos en la declaración de variables; el tipo de la variable se determina por el contexto en el cual se emplea la variable. Es decir, si se asigna un valorstringa una variable$var, entonces$varse convierte en unstring. Si un valorintegeres entonces asignado a la misma variable$var, ésta se convierte eninteger.

Un ejemplo de la conversión de tipos automática de PHP es el operador suma '+'. Si al menos uno de los operandos esfloat, entonces ambos operandos son evaluados comofloats y el resultado será unfloat. De otra manera, los operandos seran interpretados comointegers, y el resultado será entoncesinteger. Tenga en cuenta que estonoimplica que se cambien los tipos de los propios operandos; el único cambio es en como se evalúan los operandos y en el tipo de expresión en sí mismo.

<?php
$foo
="0";// $foo es string (ASCII 48)
$foo+=2;// $foo es ahora un integer (2)
$foo=$foo+1.3;// $foo es ahora un float (3.3)
$foo=5+"10 Cerditos pequeñitos";// $foo es integer (15)
$foo=5+"10 Cerdos pequeños";// $foo es integer (15)
?>

Si considera confusos los últimos dos ejemplos anteriores, consulteConversión de cadenas a números.

Para forzar a que una variable sea evaluada como un determinado tipo, consulte la secciónForzado de tipos. Para cambiar el tipo de variable, consulte la funciónsettype().

Para probar cualquiera de los ejemplos de esta sección, utilice la funciónvar_dump().

Nota:

El comportamiento de la conversión automática enarrayestá actualmente sin definir.

Tambien, debido a que PHP soporta el indexado destringmediante compensaciones mediante la misma sintaxis empleada en el indexado dearrays, los siguientes ejemplos son válidos para todas las versiones de PHP:

<?php
$a
='car';// $a es un string
$a[0] ='b';// $a sigue siendo un string
echo$a;// bar
?>

Consulte la secciónAcceso a cadenas mediante caracterespara más información.

Forzado de tipos

El forzado de tipos en PHP funciona de la misma manera que en C:, donde el nombre del tipo deseado se escribe entre paréntesis antes de la variable que se quiera forzar.

<?php
$foo
=10;// $foo es un integer
$bar= (boolean)$foo;// $bar es un boolean
?>

Los siguientes forzados de tipos están permitidos:

  • (int), (integer) - forzado ainteger
  • (bool), (boolean) - forzado aboolean
  • (float), (double), (real) - forzado afloat
  • (string) - forzado astring
  • (array) - forzado aarray
  • (object) - forzado aobject
  • (unset) - forzado aNULL(PHP 5)

El forzado (binary) y el soporte del prefijo b fueron añadidos en PHP 5.2.1

Fíjese que se permiten las tabulaciones y espacios dentro de los paréntesis, por lo que los siguientes ejemplos son funcionalmente equivalentes:

<?php
$foo
= (int)$bar;
$foo= ( int )$bar;
?>

Forzado literal destrings y variables astrings binarios:

<?php
$binary
= (binary)$string;
$binary=b"binary string";
?>

Nota:

El lugar de forzar una variable astring, tambien se puede encerrar la variable entre comillas dobles.

<?php
$foo
=10;// $foo es un integer
$str="$foo";// $str es un string
$fst= (string)$foo;// $fst es tambien un string

// Esto muestra que "son lo mismo"
if ($fst===$str) {
echo
"son lo mismo";
}
?>

Puede que no sea obvio que sucede exactamente cuando se fuerzan ciertos tipos. Para más información, consulte estas secciones:




Variables

Tabla de contenidos


Conceptos básicos

En PHP las variables se representan con un signo de dólar seguido por el nombre de la variable. El nombre de la variable es sensible a minúsculas y mayúsculas.

Los nombres de variables siguen las mismas reglas que otras etiquetas en PHP. Un nombre de variable válido tiene que empezar con una letra o un carácter de subrayado (underscore), seguido de cualquier número de letras, números y caracteres de subrayado. Como expresión regular se podría expresar como: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'

Nota:Para los propósitos de este manual, una letra es a-z, A-Z, y los bytes del 127 al 255 (0x7f-0xff).

Nota:$thises una variable especial que no puede ser asignada.

Para más información sobre funciones relacionadas con variables, vea laReferencia de Funciones de Variables.

<?php
$var
='Roberto';
$Var='Juan';
echo
"$var,$Var";// imprime "Roberto, Juan"

$4site='aun no';// inválido; comienza con un número
$_4site='aun no';// válido; comienza con un carácter de subrayado
$täyte='mansikka';// válido; 'ä' es ASCII (Extendido) 228
?>

De forma predeterminada, las variables siempre se asignan por valor. Esto significa que cuando se asigna una expresión a una variable, el valor completo de la expresión original se copia en la variable de destino. Esto quiere decir que, por ejemplo, después de asignar el valor de una variable a otra, los cambios que se efectúen a una de esas variables no afectará a la otra. Para más información sobre este tipo de asignación, veaExpresiones.

PHP también ofrece otra forma de asignar valores a las variables:asignar por referencia. Esto significa que la nueva variable simplemente referencia (en otras palabras, "se convierte en un alias de" ó "apunta a") la variable original. Los cambios a la nueva variable afectan a la original, y viceversa.

Para asignar por referencia, simplemente se antepone un signo ampersand (&) al comienzo de la variable cuyo valor se está asignando (la variable fuente). Por ejemplo, el siguiente segmento de código produce la salida 'Mi nombre es Bob' dos veces:

<?php
$foo
='Bob';// Asigna el valor 'Bob' a $foo
$bar= &$foo;// Referenciar $foo vía $bar.
$bar="Mi nombre es$bar";// Modifica $bar...
echo$bar;
echo
$foo;// $foo también se modifica.
?>

Algo importante a tener en cuenta es que sólo las variables con nombre pueden ser asignadas por referencia.

<?php
$foo
=25;
$bar= &$foo;// Esta es una asignación válida.
$bar= &(24*7);// Inválida; referencia una expresión sin nombre.

functiontest()
{
return
25;
}

$bar= &test();// Inválido.
?>

No es necesario inicializar variables en PHP, sin embargo, es una muy buena práctica. Las variables no inicializadas tienen un valor predeterminado de acuerdo a su tipo dependiendo del contexto en el que son usadas - las booleanas se asumen comofalse, los enteros y flotantes como cero, las cadenas (p.ej. usadas enecho) se establecen como una cadena vacía y los arrays se convierten en un array vacío.

Ejemplo #1 Valores predeterminados en variables sin inicializar

<?php
// Una variable no definida Y no referenciada (sin contexto de uso); imprime NULL
var_dump($variable_indefinida);

// Uso booleano; imprime 'false' (Vea operadores ternarios para más información sobre esta sintaxis)
echo($booleano_indefinido?"true\n":"false\n");

// Uso de una cadena; imprime 'string(3) "abc"'
$cadena_indefinida.='abc';
var_dump($cadena_indefinida);

// Uso de un entero; imprime 'int(25)'
$int_indefinido+=25;// 0 + 25 => 25
var_dump($int_indefinido);

// Uso de flotante/doble; imprime 'float(1.25)'
$flotante_indefinido+=1.25;
var_dump($flotante_indefinido);

// Uso de array; imprime array(1) { [3]=> string(3) "def" }
$array_indefinida[3] ="def";// array() + array(3 => "def") => array(3 => "def")
var_dump($array_indefinida);

// Uso de objetos; crea un nuevo objeto stdClass (vea http://www.php.net/manual/en/reserved.classes.php)
// Imprime: object(stdClass)#1 (1) { ["foo"]=> string(3) "bar" }
$objeto_indefinido->foo='bar';
var_dump($objeto_indefinido);
?>

Depender del valor predeterminado de una variable sin inicializar es problemático al incluir un archivo en otro que use el mismo nombre de variable. Un error de nivelE_NOTICEes emitido cuendo se trabaja con variables sin inicializar, con la excepción del caso en el que se anexan elementos a un array no inicializado. La construcción del lenguajeisset()puede ser usada para detectar si una variable ya ha sido inicializada.



Variables Predefinidas

PHP proporciona una gran cantidad de variables predefinidas a cualquier script que se ejecute. Muchas de éstas, sin embargo, no pueden ser completamente documentadas ya que dependen del servidor que esté corriendo, la versión y configuración de dicho servidor, y otros factores. Algunas de estas variables no estarán disponibles cuando se ejecute PHP desde lalínea de comandos. Para obtener una lista de estas variables, por favor vea la sección sobreVariables Predefinidas Reservadas.

PHP ofrece un conjunto adicional de arrays predefinidas que contienen variables del servidor web, el entorno y entradas del usuario. Estos nuevos arrays son un poco especiales porque son automáticamente globales. Por esta razón, son conocidas a menudo como "superglobales". Las superglobales se mencionan más abajo; sin embargo para una lista de sus contenidos y más información sobre variables predefinidas en PHP, por favor consulte la secciónVariables predefinidas reservadas. Asimismo, podrá notar cómo las antiguas variables predefinidas ($HTTP_*_VARS) todavía existen.

Nota:Variables variables

Las superglobales no pueden ser usadas comovariables variablesal interior de funciones o métodos de clase.

Nota:

Aún cuando las superglobales yHTTP_*_VARSpueden existir al mismo tiempo; estas variables no son idénticas, así que modificar una no cambia la otra.

Si ciertas variables no son definidas envariables_order, los arrays de PHP predefinidos asociados a estas, estarán vacíos.



Ámbito de las variables

El ámbito de una variable es el contexto dentro del que la variable está definida. La mayor parte de las variables PHP sólo tienen un ámbito simple. Este ámbito simple también abarca los ficheros incluídos y los requeridos. Por ejemplo:

<?php
$a
=1;
include
'b.inc';
?>

Aquí, la variable$aestará disponible al interior del script incluidob.inc. Sin embargo, al interior de las funciones definidas por el usuario se introduce un ámbito local a la función. Cualquier variable usada dentro de una función está, por omisión, limitada al ámbito local de la función. Por ejemplo:

<?php
$a
=1;/* ámbito global */

functiontest()
{
echo
$a;/* referencia a una variable del ámbito local */
}

test();
?>

Este script no producirá salida, ya que la sentencia echo utiliza una versión local de la variable$a, a la que no se ha asignado ningún valor en su ámbito. Puede que usted note que hay una pequeña diferencia con el lenguaje C, en el que las variables globales están disponibles automáticamente dentro de la función a menos que sean expresamente sobreescritas por una definición local. Esto puede causar algunos problemas, ya que la gente puede cambiar variables globales inadvertidamente. En PHP, las variables globales deben ser declaradas globales dentro de la función si van a ser utilizadas dentro de dicha función.

La palabra claveglobal

En primer lugar, un ejemplo de uso deglobal:

Ejemplo #1 Uso deglobal

<?php
$a
=1;
$b=2;

function
Suma()
{
global
$a,$b;

$b=$a+$b;
}

Suma();
echo
$b;
?>

El script anterior producirá la salida3. Al declarar$ay$bglobales dentro de la función, todas las referencias a tales variables se referirán a la versión global. No hay límite al número de variables globales que se pueden manipular dentro de una función.

Un segundo método para acceder a las variables desde un ámbito global es usando el array$GLOBALS. El ejemplo anterior se puede reescribir así:

Ejemplo #2 Uso de$GLOBALSen lugar de global

<?php
$a
=1;
$b=2;

function
Suma()
{
$GLOBALS['b'] =$GLOBALS['a'] +$GLOBALS['b'];
}

Suma();
echo
$b;
?>

El array$GLOBALSes un array asociativo con el nombre de la variable global como clave y los contenidos de dicha variable como el valor del elemento del array.$GLOBALSexiste en cualquier ámbito, esto ocurre ya que$GLOBALSes unasuperglobal. Aquí hay un ejemplo que demuestra el poder de las superglobales:

Ejemplo #3 Ejemplo que demuestra las superglobales y el ámbito

<?php
functiontest_global()
{
// La mayoría de variables predefinidas no son "super" y requieren
// 'global' para estar disponibles al ámbito local de las funciones.
global$HTTP_POST_VARS;

echo
$HTTP_POST_VARS['name'];

// Las superglobales están disponibles en cualquier ámbito y no
// requieren 'global'. Las superglobales están disponibles desde
// PHP 4.1.0, y ahora HTTP_POST_VARS se considera obsoleta.
echo$_POST['name'];
}
?>

Nota:

Utilizar una claveglobalfuera de una función no es un error. Esta puede ser utilizada aún si el fichero está incluido desde el interior de una función.

Uso de variablesstatic

Otra característica importante del ámbito de las variables es la variableestática. Una variable estática existe sólo en el ámbito local de la función, pero no pierde su valor cuando la ejecución del programa abandona este ámbito. Consideremos el siguiente ejemplo:

Ejemplo #4 Ejemplo que demuestra la necesidad de variables estáticas

<?php
functiontest()
{
$a=0;
echo
$a;
$a++;
}
?>

Esta función tiene poca utilidad ya que cada vez que es llamada asigna a$ael valor0e imprime un0. La sentencia$a++, que incrementa la variable, no sirve para nada, ya que en cuanto la función finaliza, la variable$adesaparece. Para hacer una función útil para contar, que no pierda la pista del valor actual del conteo, la variable$adebe declararse como estática:

Ejemplo #5 Ejemplo del uso de variables estáticas

<?php
functiontest()
{
static
$a=0;
echo
$a;
$a++;
}
?>

Ahora,$ase inicializa únicamente en la primera llamada a la función, y cada vez que la funcióntest()es llamada, imprimirá el valor de$ay lo incrementa.

Las variables estáticas también proporcionan una forma de manejar funciones recursivas. Una función recursiva es la que se llama a sí misma. Se debe tener cuidado al escribir una función recursiva, ya que puede ocurrir que se llame a sí misma indefinidamente. Hay que asegurarse de implementar una forma adecuada de terminar la recursión. La siguiente función cuenta recursivamente hasta 10, usando la variable estática$countpara saber cuándo parar:

Ejemplo #6 Variables estáticas con funciones recursivas

<?php
functiontest()
{
static
$count=0;

$count++;
echo
$count;
if (
$count<10) {
test();
}
$count--;
}
?>

Nota:

Las variables estáticas pueden ser declaradas como se ha visto en los ejemplos anteriores. Desde PHP 5.6 se pueden asignar valores a estas variables que sean el resultado de expresiones, aunque no se pueden usar funciones aquí, lo cual causaría un eror de análisis.

Ejemplo #7 Declaración de variables estáticas

<?php
functionfoo(){
static
$int=0;// correcto
static$int=1+2;// correcto (a partir de PHP 5.6)
static$int=sqrt(121);// incorrecto (ya que es una función)

$int++;
echo
$int;
}
?>

Nota:

Las declaraciones estáticas son resueltas en tiempo de compilación.

Referencias con variablesglobalystatic

El motor Zend 1, utilizado por PHP 4, implementa los modificadoresstaticyglobalpara variables en términos dereferencias. Por ejemplo, una variable global verdadera importada dentro del ámbito de una función conglobalcrea una referencia a la variable global. Esto puede ser causa de un comportamiento inesperado, tal y como podemos comprobar en el siguiente ejemplo:

<?php
functionprueba_referencia_global() {
global
$obj;
$obj= &newstdclass;
}

function
prueba_no_referencia_global() {
global
$obj;
$obj= newstdclass;
}

prueba_referencia_global();
var_dump($obj);
prueba_no_referencia_global();
var_dump($obj);
?>

El resultado del ejemplo sería:


NULL
object(stdClass)(0) {
}

Un comportamiento similar se aplica astatic. Las referencias no son almacenadas estáticamente.

<?php
function &obtener_instancia_ref() {
static
$obj;

echo
'Objeto estático: ';
var_dump($obj);
if (!isset(
$obj)) {
// Asignar una referencia a la variable estática
$obj= &newstdclass;
}
$obj->property++;
return
$obj;
}

function &
obtener_instancia_no_ref() {
static
$obj;

echo
'Objeto estático: ';
var_dump($obj);
if (!isset(
$obj)) {
// Asignar el objeto a la variable estática
$obj= newstdclass;
}
$obj->property++;
return
$obj;
}

$obj1=obtener_instancia_ref();
$aun_obj1=obtener_instancia_ref();
echo
"\n";
$obj2=obtener_instancia_no_ref();
$aun_obj2=obtener_instancia_no_ref();
?>

El resultado del ejemplo sería:


Objeto estático: NULL
Objeto estático: NULL

Objeto estático: NULL
Objeto estático: object(stdClass)(1) {
["property"]=>
int(1)
}

Este ejemplo demuestra que al asignar una referencia a una variable estática, esta no esrecordadacuando se invoca la funcion&obtener_instancia_ref()por segunda vez.



Variables variables

A veces es conveniente tener nombres de variables variables. Dicho de otro modo, son nombres de variables que se pueden definir y usar dinámicamente. Una variable normal se establece con una sentencia como:

<?php
$a
='hola';
?>

Una variable variable toma el valor de una variable y lo trata como el nombre de una variable. En el ejemplo anterior,hola, se puede usar como el nombre de una variable utilizando dos signos de dólar. Es decir:

<?php
$$a='mundo';
?>

En este momento se han definido y almacenado dos variables en el árbol de símbolos de PHP:$a, que contiene "hola", y$hola, que contiene "mundo". Es más, esta sentencia:

<?php
echo"$a${$a}";
?>

produce el mismo resultado que:

<?php
echo"$a$hola";
?>

esto quiere decir que ambas producen el resultado:hola mundo.

Para usar variables variables con arrays hay que resolver un problema de ambigüedad. Si se escribe$$a[1], el intérprete necesita saber si nos referimos a utilizar$a[1]como una variable, o si se pretendía utilizar$$acomo variable y el índice [1] como índice de dicha variable. La sintaxis para resolver esta ambigüedad es:${$a[1]}para el primer caso y${$a}[1]para el segundo.

También se puede acceder a las propiedades de una clase usando el nombre de propiedad variable. Este será resuelto dentro del ámbito del cual se hizo la llamada. Por ejemplo, en la expresión$foo->$bar, se buscará$baren el ámibto local y se empleará su valor será como el nombre de la propiedad de$foo. Esto también es cierto si$bares un acceso a un array.

Precaución

Además, derreferenciar una propiedad variable que es un array tiene diferente semántica entre PHP 5 y PHP 7. Laguías de migración de PHP 7.0incluye más detalles sobre los tipos de expresiones que han cambiado, y cómo colocar llaves para evitar ambigüedades.

También se pueden usar llaves para delimitar de forma clara el nombre de la propiedad. Son muy útila al acceder a valores dentro una propiedad que contiene un array, cuando el nombre de la propiedad está compuesto de múltiples partes, o cuando el nombre de la propiedad contiene caracteres que de otro modo no son válidos (p.ej. desdejson_decode()oSimpleXML).

Ejemplo #1 Ejemplo de propiedad variable

<?php
classfoo{
var
$bar='Soy bar.';
var
$arr= array('Soy A.','Soy B.','Soy C.');
var
$r='Soy r.';
}

$foo= newfoo();
$bar='bar';
$baz= array('foo','bar','baz','quux');
echo
$foo->$bar."\n";
echo
$foo->{$baz[1]} ."\n";

$start='b';
$end='ar';
echo
$foo->{$start.$end} ."\n";

$arr='arr';
echo
$foo->$arr[1] ."\n";
echo
$foo->{$arr[1]} ."\n";

?>

El resultado del ejemplo sería:


Soy bar.
Soy bar.
Soy bar.
Soy r.

Advertencia

Por favor tenga en cuenta que las variables variables no pueden usarse con losArrays superglobalesde PHP al interior de funciones o métodos de clase. La variable$thises también una variable especial que no puede ser referenciada dinámicamente.



Variables desde fuentes externas

Formularios HTML (GET y POST)

Cuando se envía un formulario a un script de PHP, la información de dicho formulario pasa a estar automáticamente disponible en el script. Existen algunas formas de acceder a esta información, por ejemplo:

Ejemplo #1 Un formulario HTML sencillo

<form action="foo.php" method="post">
Nombre usuario: <input type="text" name="username" /><br />
Email: <input type="text" name="email" /><br />
<input type="submit" name="submit" value="¡Enviarme!" />
</form>

A partir de PHP 5.4.0, solamente existen dos maneras de acceder a datos desde formularios HTML. Los métodos disponibles actualmente se enumeran a continuación:

Ejemplo #2 Acceso a datos de un formulario HTML sencillo con POST

<?php
echo $_POST['username'];
echo $_REQUEST['username'];
?>

Habían otras formas de acceder a la entrada del usuario en versiones antiguas de PHP. Están enumeradas abajo. Véase el historial de cambios al final para más detalles.

Ejemplo #3 Old methods of accessing user input

<?php
// OJO: estos métodos ya NO ESTÁN soportados.
// Los válidos están descritos arriba.

// Usar import_request_variables() - esta función ha sido eliminada en PHP 5.4.0
import_request_variables('p','p_');
echo
$p_username;

// Estas variables predefinidas fueron eliminadas en PHP 5.4.0
echo$HTTP_POST_VARS['username'];

// Usar register_globals. Esta característica fue eliminada en PHP 5.4.0
echo$username;
?>

Usar un formulario con GET es similar excepto en el uso de variables predefinidas, que en este caso serán del tipo GET. GET también se usa conQUERY_STRING(la información despues del símbolo '?' en una URL). Por ejemplohttp://www.example.com/test.php?id=3contiene datos GET que son accesibles con$_GET['id']. Véase también$_REQUEST.

Nota:

Puntos y espacios en nombres de variables son convertidos a guiones bajos. Por ejemplo<input name="a.b" />se convierte en$_REQUEST["a_b"].

PHP también entiende arrays en el contexto de variables de formularios (vea lafaq relacionada). Se puede, por ejemplo, agrupar juntas variables relacionadas o usar esta característica para obtener valores de una entrada "select" múltiple. Por ejemplo, vamos a mandar un formulario a sí mismo y a presentar los datos cuando se reciban:

Ejemplo #4 Variables de formulario más complejas

<?php
if ($_POST) {
echo
'<pre>';
echo
htmlspecialchars(print_r($_POST,true));
echo
'</pre>';
}
?>
<form action="" method="post">
Nombre: <input type="text" name="personal[nombre]" /><br />
Email: <input type="text" name="personal[email]" /><br />
Cerveza: <br />
<select multiple name="cerveza[]">
<option value="warthog">Warthog</option>
<option value="guinness">Guinness</option>
<option value="stuttgarter">Stuttgarter Schwabenbräu</option>
</select><br />
<input type="submit" value="¡enviarme!" />
</form>

Nombres de variables tipo IMAGE SUBMIT

Cuando se envía un formulario, es posible usar una imagen en vez del botón estándar "submit":

<input type="image" src="image.gif" name="sub" />

Cuando el usuario hace click en cualquier parte de la imagen, el formulario que la acompaña se transmitirá al servidor con dos variables adicionales,sub_xysub_y. Éstas contienen las coordenadas del clic del usuario dentro de la imagen. Los más experimentados puede notar que los nombres de variable enviados por el navegador contienen un guión en vez de un subrayado (guión bajo), pero PHP convierte el guión en subrayado automáticamente.

Cookies HTTP

PHP soporta cookies de HTTP de forma transparente tal y como están definidas en» RFC 6265. Las cookies son un mecanismo para almacenar datos en el navegador y así rastrear o identificar a usuarios que vuelven. Se pueden crear cookies usando la funciónsetcookie(). Las cookies son parte de la cabecera HTTP, así que se debe llamar a la función SetCookie antes de que se envíe cualquier salida al navegador. Es la misma restricción que para la funciónheader(). Los datos de una cookie están disponibles en el array de datos de la cookies apropiada, tal como$_COOKIEy$_REQUEST. Véase la página desetcookie()del manual para más detalles y ejemplos.

Si se quieren asignar múltiples valores a una sola cookie, basta con asignarlo como un array. Por ejemplo:

<?php
setcookie
("MiCookie[foo]",'Prueba 1',time()+3600);
setcookie("MiCookie[bar]",'Prueba 2',time()+3600);
?>

Esto creará dos cookies separadas aunqueMiCookieserá un array simple en el script. Si se quiere definir una sola cookie con valores múltiples, considere el uso de la funciónserialize()oexplode()primero en el valor.

Nótese que una cookie reemplazará a una cookie anterior que tuviese el mismo nombre en el navegador a menos que la ruta o el dominio fuesen diferentes. Así, para una aplicación de carrito de compras se podría querer mantener un contador e ir pasándolo. Es decir:

Ejemplo #5 Un ejemplo desetcookie()

<?php
if (isset($_COOKIE['conteo'])) {
$conteo=$_COOKIE['conteo'] +1;
} else {
$conteo=1;
}
setcookie('conteo',$conteo,time()+3600);
setcookie("Carrito[$conteo]",$item,time()+3600);
?>

Puntos en los nombres de variables de entrada

Típicamente, PHP no altera los nombres de las variables cuando se pasan a un script. Sin embargo, hay que notar que el punto no es un carácter válido en el nombre de una variable PHP. Para conocer la razón, considere el siguiente ejemplo:

<?php
$varname
.ext;/* nombre de variable inválido */
?>
Lo que el intérprete vé es el nombre de una variable$varname, seguido por el operador de concatenación, y seguido por la cadena pura (es decir, una cadena sin entrecomillar que no coincide con ninguna palabra clave o reservada conocida) 'ext'. Obviamente, no se pretendía que fuese éste el resultado.

Por esta razón, es importante hacer notar que PHP reemplazará automáticamente cualquier punto en los nombres de variables de entrada por guiones bajos (subrayados).

Determinación de los tipos de variables

Dado que PHP determina los tipos de las variables y los convierte (generalmente) según lo que necesita, no siempre resulta obvio de qué tipo es una variable dada en un momento concreto. PHP incluye varias funciones que descubren de qué tipo es una variable:gettype(),is_array(),is_float(),is_int(),is_object(), yis_string(). Vea también el capítulo sobreTipos.

Historial de cambios

VersiónDescripción
7.2.34, 7.3.23, 7.4.11Losnombresde las cookies entrantes ya no son con url-decoded por razones de seguridad.




Constantes

Tabla de contenidos

Una constante es un identificador (nombre) para un valor simple. Como el nombre sugiere, este valor no puede variar durante la ejecución del script (a excepción de lasconstantes mágicas, que en realidad no son constantes). Por defecto, una constante distingue mayúsculas y minúsculas. Por convención, los identificadores de constantes siempre se declaran en mayúsculas.

El nombre de una constante sigue las mismas reglas que cualquier otra etiqueta de PHP. Un nombre de constante válido empieza por una letra o guion bajo, seguido por cualquier número de letras, números o guiones bajos. Usando una expresión regular, se representaría de la siguiente manera:[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*

Ejemplo #1 Nombres de constantes correctos e incorrectos

<?php

// Nombres de constantes correctos
define("FOO","something");
define("FOO2","something else");
define("FOO_BAR","something more");

// Nombres de constantes incorrectos
define("2FOO","something");

// Esto es válido, pero debe evitarse:
// PHP podría cualquier día proporcionar una constante mágica
// que rompiera el script
define("__FOO__","something");

?>

Nota:Para nuestros propósitos, una letra está entre los carácteres a-z, A-Z, y los caracteres ASCII del 127 hasta el 255 (0x7f-0xff).

Igual que lassuperglobals, el acceso a una constante es global. Se puede acceder a constantes desde cualquier sitio del script sin importar desde donde. Para más información en el acceso, lea el manual en la secciónacceso a variables.


Sintaxis

Se puede definir una constante usando la funcióndefine()o con la palabra reservadaconstfuera de la definición de una clase a partir PHP 5.3.0. Mientras quedefine()permite definir una constante con una expresión arbitraria, la palabra reservadaconsttiene retricciones que se resumen en el siguiente párrafo. Una vez que la constante está definida, no puede ser cambiada o redifinida.

Antes de PHP 5.6, al emplear la palabra reservadaconst, solamente los datos escalares (boolean,integer,floatystring) pueder estar contenidos en constante. Desde PHP 5.6 en adelante, es posible definir una constante como una expresión escalar, y también es posible definir unarrayconstante. Es posible definir constantes como unresource, pero debería evitarse, ya que podría ocasionar resultados inesperados.

Para obtener el valor de una constante solo es necesario especificar su nombre. A diferencia de las variables,nose debe prefijar una constante con el signo$. También se puede usar la funciónconstant()para leer el valor de una constante si se desea obtener el valor de una constante de forma dinámica. Useget_defined_constants()para obtener una lista de todas las constantes definidas.

Nota:Las contantes y las variables (globales) se encuentran en un espacio de nombres distinto. Esto implica que por ejemplotruey$TRUEson diferentes.

Si se usa una constante que todavía no está definida, PHP asume que se está refiriendo al nombre de la constante en si, igual que si fuera unastring(CONSTANT vs "CONSTANT"). Cuando esto suceda, se mostrará un error de nivelE_NOTICE. Ver también la sección en el manual de porqué$foo[bar]es incorrecto (a no ser que primerodefine()barcomo constante). Esto no se aplica a lasconstantes (completamente) cualificadas, lo cual emitirá un error fatal si no está definida. Si simplemente quiere comprobar si una constante está definida, use la funcióndefined().

Estas son las diferencias entre constantes y variables:

  • Las constantes no llevan el signo dólar ($), como prefijo.
  • Antes de PHP 5.3, las constantes solo podían ser definidas usando la funcióndefine(), y no por simple asignación.
  • Las constantes pueden ser definidas y accedidas desde cualquier sitio sin importar las reglas de acceso de variables.
  • Las constantes no pueden ser redefinidas o eliminadas una vez se han definido; y
  • Las constantes podrían evaluarse como valores escalares. A partir de PHP 5.6 es posible definir una constante de array con la palabra reservadaconst, y, a partir de PHP 7, las constantes de array también se pueden definir condefine(). Se pueden utilizar arrays en expresiones escalares constantes (por ejemplo,const FOO = array(1,2,3)[0];), aunque el resultado final debe ser un valor de un tipo permitido.

Ejemplo #1 Definición de constantes

<?php
define
("CONSTANTE","Hola mundo.");
echo
CONSTANTE;// muestra "Hola mundo."
echoConstante;// muestra "Constant" y se emite un aviso.
?>

Ejemplo #2 Definición de constantes usando el la palabra reservadaconst

<?php
// Funciona a partir de PHP 5.3.0
constCONSTANTE='Hola Mundo';

echo
CONSTANTE;

// Funciona a partir de PHP 5.6.0
constOTRA_CONSTANTE=CONSTANTE.'; Adiós Mundo';
echo
OTRA_CONSTANTE;

const
ANIMALES= array('perro','gato','pájaro');
echo
ANIMALES[1];// muestra "gato"

// Funciona a partir de PHP 7
define('ANIMALES', array(
'perro',
'gato',
'pájaro'
));
echo
ANIMALES[1];// muestra "gato"
?>

Nota:

A diferencia de definir constantes usandodefine(), las constantes definidas con la palabra claveconstdeben declararse en el nivel superior del entorno de la aplicación porque se definen en tiempo de ejecución. Esto significa que no pueden declararse dentro de funciones, bucles, sentenciasifo bloquestry/catch.

Vea tambiénConstantes de clase.



Constantes predefinidas

PHP ofrece un gran número deconstantes predefinidasa cualquier script en ejecucción. Muchas de estas constantes, sin embargo, son creadas por diferentes extensiones, y sólo estarán presentes si dichas extensiones están disponibles, bien por carga dinámica o porque han sido compiladas.

Hay nueve constantes mágicas que cambian dependiendo de dónde se emplean. Por ejemplo, el valor de__LINE__depende de la línea en que se use en el script. Todas estas constantes «mágicas» se resuelven durante la compilación, a diferencia de las constantes normales que lo hacen durante la ejecución. Estas constantes especiales son sensibles a mayúsculas Estas constantes especiales distinguen mayúsculas y minúsculas, y son las siguientes:

Varias constantes "mágicas" de PHP
NombreDescripción
__LINE__El número de línea actual en el fichero.
__FILE__Ruta completa y nombre del fichero con enlaces simbólicos resueltos. Si se usa dentro de un include, devolverá el nombre del fichero incluido.
__DIR__Directorio del fichero. Si se utiliza dentro de un include, devolverá el directorio del fichero incluído. Esta constante es igual quedirname(__FILE__). El nombre del directorio no lleva la barra final a no ser que esté en el directorio root.
__FUNCTION__Nombre de la función.
__CLASS__Nombre de la clase. El nombre de la clase incluye el namespace declarado en (p.e.j.Foo\Bar). Tenga en cuenta que a partir de PHP 5.4 __CLASS__ también funciona con traits. Cuando es usado en un método trait, __CLASS__ es el nombre de la clase del trait que está siendo utilizado.
__TRAIT__El nombre del trait. El nombre del trait incluye el espacio de nombres en el que fue declarado (p.e.j.Foo\Bar).
__METHOD__Nombre del método de la clase.
__NAMESPACE__Nombre del espacio de nombres actual.
ClassName::classEl nombre de clase completamente cualificado. Véase también::class.

Véase tambiénget_class(),get_object_vars(),file_exists()yfunction_exists().

Historial de cambios

VersiónDescripción
5.5.0Se añadió la constante mágica::class
5.4.0Se añadió la constante__TRAIT__
5.3.0Se añadieron las constantes__DIR__y__NAMESPACE__
5.0.0Se añadió la constante__METHOD__
5.0.0Antes de esta versión, los valores de algunas constantes mágicas estaban siempre en minúsculas. Ahora todas ellas están en mayúsculas (contienen nombres mientras eran declaradas).
4.3.0Se añadieron las constantes__FUNCTION__y__CLASS__
4.0.2__FILE__siempre contiene una ruta absoluta con enlaces simbólicos resueltos, mientras que en versiones antiguas contenía una ruta relativa bajo algunas circunstancias




Expresiones

La expresiones son los bloques de construcción más importantes de PHP. En PHP casi todo lo que se escribe es una expresión. La manera más simple y acertada de definir lo que es una expresión es «cualquier cosa que tiene un valor».

Las formas más básicas de expresiones son las constantes y las variables. Cuando se escribe "$a= 5", se está asignando '5' a$a. '5', obviamente, tiene el valor 5, o en otras palabras, '5' es una expresión con el valor de 5 (en este caso, '5' es una constante entera).

Después de esta asignación, se espera que el valor de$asea 5 también, por lo que si se escribe$b=$a, se espera que esto se comporte tal como si se escribiera$b= 5. En otras palabras,$aes también una expresión con el valor 5. Si todo funciona bien, esto es exactamente lo que sucederá.

Un ejemplo de expresiones algo más complejo son las funciones. Por ejemplo, considere la siguiente función:

<?php
functionfoo()
{
return
5;
}
?>

Asumiendo que está familiarizado con el concepto de función (si no lo está, échele una ojeada al capítulo sobrefunciones), asumirá que escribir$c = foo()es esencialmente igual que escribir$c = 5. Y está en lo cierto. Las funciones son expresiones con el valor de sus valores devueltos. Ya quefoo()devuelve 5, el valor de la expresión 'foo()' es 5. Normalmente las funciones no sólo devuelven un valor estático, sino que computan algo.

Por supuesto, los valores en PHP no tienen que ser enteros, y con frecuencia no lo son. PHP soporta cuatro tipos de valores escalares: valores enteros (integer), valores de coma (punto) flotante (float), valores de cadena (string) y valores booleanos (boolean) - (valores escalares son aquellos que no se pueden descomponer en piezas más pequeñas, a diferencia de las matrices, por ejemplo). PHP también soporta dos tipos compuestos (no escalares): matrices (arrays) y objetos. Cada uno de estos tipos de valores pueden ser asignados a variables o devueltos desde funciones.

PHP lleva las expresiones mucho más allá, de la misma manera que lo hacen otros lenguajes. PHP es un lenguaje orientado a expresiones, en el sentido de que casi todo es una expresión. Considere el ejemplo que ya hemos tratado, '$a= 5'. Es fácil de ver que aquí hay dos valores involucrados, el valor de la constante entera '5', y el valor de$aque ha sido actualizado a 5 también. Aunque la verdad es que existe aquí un valor adicional involucrado, que es el valor de la asignación misma. La asignación evalúa al valor asignado, en este caso 5. En la práctica, esto significa que '$a= 5', sin importar lo que haga, es una expresión con el valor 5. De este modo, escribir algo como '$b= ($a= 5)' es igual que escribir '$a= 5;$b= 5;' (el punto y coma marca el final de una sentencia). Ya que las asignaciones se analizan de derecha a izquierda, también se puede escribir '$b=$a= 5'.

Otro buen ejemplo de orientación a expresiones es el pre- y post-incremento y decremento. Los usuarios de PHP y de otros muchos lenguajes pueden estar familiarizados con la notaciónvariable++yvariable--. Éstos son losoperadores de incremento y decremento. En PHP, al igual que en C, hay dos tipos de incrementos - pre-incremento y post-incremento. Ambos esencialmente incrementan la variable, y el efecto sobre la variable es idéntico. La diferencia está con el valor de la expresión de incremento. Pre-incremento, que se escribre '++$variable', evalúa al valor incrementado (PHP incrementa la variable antes de leer su valor, de ahí el nombre de 'pre-incremento'). Post-incremento, que se escribe '$variable++' evalúa el valor original de $variable, antes de que sea incrementado (PHP incrementa la variable después de leer su valor, de ahí el nombre de 'post-incremento').

Un tipo de expresiones muy comunes son las expresiones decomparación. Estas expresiones evalúan si algo esfalse(falso) otrue(verdadero). PHP soporta > (mayor que), >= (mayor o igual que), == (igual), != (distinto), < (menor que) y <= (menor o igual que). El lenguaje también soporta un conjunto de operadores de equivalencia estricta: === (igual y del mismo tipo) y !== (diferente o de distinto tipo). Estas expresiones se usan mayormente dentro de ejecuciones condicionales, tales como la sentenciaif.

El último ejemplo de expresiones que trataremos aquí es una combinación de expresiones operador-asignación. Ya sabe que si quiere incrementar$aen 1, puede simplemente escribir '$a++' o '++$a'. Pero si lo que quiere es añadirle más de uno, por ejemplo 3, podría escribir '$a++' varias veces, pero esto, obviamente, no es una manera muy eficiente o cómoda. Una práctica mucho más común es escribir '$a=$a+ 3'. '$a+ 3' evalúa al valor de$amás 3, y se vuelve a asignar a$a, lo que resulta en incrementar$aen 3. En PHP, como en otros lenguajes como C, se puede escribir esto de una manera más abreviada, lo que con el tiempo se podría convertir en una forma más clara y rápida de entenderlo. Añadir 3 al valor actual de$apuede ser escrito '$a+= 3'. Esto significa exactamente "toma el valor de$a, añádele 3 y asígnalo de nuevo a$a". Además de ser más corto y claro, también resulta en una ejecución más rápida. El valor de '$a+= 3', al igual que el valor de una asignación normal, es el valor asignado. Observe que NO es 3, sino el valor combinado de$amás 3 (éste es el valor que es asignado a$a). Se puede usar cualquier operador compuesto de dos partes en este modo de operador-asignación, por ejemplo '$a-= 5' (restar 5 del valor de$a), '$b*= 7' (multiplicar el valor de$bpor 7), etc.

Existe una expresión más que le puede parecer rara si no la ha visto en otros lenguajes, el operador condicional ternario:

<?php
$primero
?$segundo:$tercero
?>

Si el valor de la primera subexpresión estrue(no es cero), se evalúa la segunda subexpresión, y ése será el resultado de la expresión condicional. Si no, se evalúa la tercera subexpresión, y ése será el valor.

El siguiente ejemplo debería ayudarle a comprender un poco mejor el pre- y post-incremento y las expresiones en general:

<?php
functiondoble($i)
{
return
$i*2;
}
$b=$a=5;/* asignar el valor cinco a la variable $a y $b */
$c=$a++;/* post-incremento, asignar el valor original de $a
(5) a $c */
$e=$d= ++$b;/* pre-incremento, asignar el valor incrementado de
$b (6) a $d y $e */

/* en este punto, $d y $e son iguales a 6 */

$f=doble($d++);/* asignar el doble del valor de $d antes
del incremento, 2*6 = 12, a $f */
$g=doble(++$e);/* asignar el doble del valor de $e después
del incremento, 2*7 = 14, a $g */
$h=$g+=10;/* primero, $g es incrementado en 10 y finaliza con el
valor 24. El valor de la asignación (24) es
asignado después a $h, y $h finaliza también con el
valor 24. */
?>

Algunas expresiones pueden considerarse como sentencias. En este caso, una sentencia tiene la forma 'expr ;', es decir, una expresión seguida de un punto y coma. En'$b = $a = 5;','$a = 5'es una expresión válida, pero no es una sentencia en sí. Sin embargo,'$b = $a = 5;'es una sentencia válida.

Lo último que vale la pena mencionar es el valor verdadero de las expresiones. En muchos casos, principalmente en ejecuciones condicionales y bucles, no interesa saber el valor específico de la expresión, sino sólo si el valor significatrueofalse. Las constantestrueyfalse(insensible a mayúsculas-minúsculas) son los dos valores booleanos posibles. Cuando es necesario, una expresión es convertida automáticamente al tipo boolean. Véase lasección sobre conversión de tipospara más detalles.

PHP proporciona una implementación completa y potente de expresiones, y documentarla por completo va más allá del ámbito de este manual. Los ejemplos de arriba deberían darle una buena idea de lo que son las expresiones y cómo construir expresiones útiles. Durante el resto de este manual se escribiráexprpara indicar cualquier expresión de PHP válida.



Operadores

Tabla de contenidos

Un operador es algo que toma uno más valores (o expresiones, en la jerga de programación) y produce otro valor (de modo que la construcción en si misma se convierte en una expresión).

Los operadores se pueden agrupar de acuerdo con el número de valores que toman. Los operadores unarios toman sólo un valor, por ejemplo!(eloperador lógico de negación) o++(eloperador de incremento). Los operadores binarios toman dos valores, como los familiaresoperadores aritméticos+(suma) y-(resta), y la mayoría de los operadores de PHP entran en esta categoría. Finalmente, hay sólo unoperador ternario,? :, el cual toma tres valores; usualmente a este se le refiere simplemente como "el operador ternario" (aunque podría tal vez llamarse más correctamente como el operador condicional).

Una lista completa de operadores de PHP sigue en la secciónPrecedencia de Operadores. La sección también explica la precedencia y asociatividad de los operadores, las cuales gobiernan exactamente cómo son evaluadas expresiones que contienen varios diferentes operadores.


Precedencia de operadores

La precedencia de un operador indica qué tan "estrechamente" se unen dos expresiones juntas. Por ejemplo, en la expresión1 + 5 * 3, la respuesta es16y no18porque el operador de multiplicación ("*") tiene una precedencia mayor que el operador de adición ("+"). Los paréntesis pueden ser usados para forzar la precedencia, si es necesario. Por ejemplo:(1 + 5) * 3se evalúa como18.

Cuando los operadores tienen igual precedencia su asociatividad decide cómo se agrupan. Por ejemplo "-" tiene asociatividad a izquierda, así1 - 2 - 3se agrupa como(1 - 2) - 3y se evalúa a-4. "=", por otra parte, tiene asociatividad a derecha, así$a = $b = $cse agrupa como$a = ($b = $c).

Los operadores de igual precedencia que no son asociativos no pueden usarse unos junto a otros, por ejemplo,1 < 2 > 1es ilegal en PHP. La expresión1 <= 1 == 1, por otro lado, es legal, ya que el operador==tiene menos precedencia que el operador<=.

El uso de paréntesis, incluso cuando no es estrictamente necesario, a menudo puede aumentar la legibilidad del código haciendo grupos explícitamente en lugar de confiar en la precedencia y asociatividad implícitas del operador.

La siguiente tabla enumera los operadores en orden de precedencia, con los de más alta precedencia al inicio. Los operadores en la misma línea tienen igual precedencia, en cuyo caso la asociatividad decide el agrupamiento.

Precedencia de operadores
AsociatividadOperadoresInformación adicional
no asociativoclonenewcloneandnew
izquierda[array()
derecha**aritmética
derecha++--~(int)(float)(string)(array)(object)(bool)@tiposeincremento/decremento
no asociativoinstanceoftipos
derecha!lógico
izquierda*/%aritmética
izquierda+-.aritméticaystring
izquierda<<>>bit a bit
no asociativo<<=>>=comparación
no asociativo==!====!==<><=>comparación
izquierda&bit a bityreferencias
izquierda^bit a bit
izquierda|bit a bit
izquierda&&lógico
izquierda||lógico
derecha??comparación
izquierda? :ternario
derecha=+=-=*=**=/=.=%=&=|=^=<<=>>=asignación
izquierdaandlógico
izquierdaxorlógico
izquierdaorlógico

Ejemplo #1 Asociatividad

<?php
$a
=3*3%5;// (3 * 3) % 5 = 4
// la asociatividad del operador ternario difiere de C/C++
$a=true?0:true?1:2;// (true ? 0 : true) ? 1 : 2 = 2

$a=1;
$b=2;
$a=$b+=3;// $a = ($b += 3) -> $a = 5, $b = 5
?>

La precedencia y asociatividad de los operadores solamente determinan cómo se agrupan las expresiones, no especifican un orden de evaluación. PHP no especifica (en general) el orden en que se evalúa una expresión y se debería evitar el código que se asume un orden específico de evaluación, ya que el comportamiento puede cambiar entre versiones de PHP o dependiendo de código circundante.

Ejemplo #2 Orden de evaluación no definido

<?php
$a
=1;
echo
$a+$a++;// podría mostrar 2 o 3

$i=1;
$array[$i] =$i++;// podría establecer el índice a 1 o 2
?>

Ejemplo #3+,-y.tienen la misma precedencia

<?php
$x
=4;
// esta línea podría resultar en una salida inesperada:
echo"x menos uno igual a ".$x-1.", o eso espero\n";
// ya que se evalúa como esta línea:
echo (("x menos uno igual a ".$x) -1) .", o eso espero\n";
// la precedencia deseada se puede forzar con paréntesis:
echo"x menos uno igual a ". ($x-1) .", o eso espero\n";
?>

El resultado del ejemplo sería:

-1, o eso espero
-1, o eso espero
x menos uno igual a 3, o eso espero

Nota:

Aunque=tiene una precedencia menor que la mayoría de los demás operadores, PHP aun permitirá expresiones similares a lo siguiente:if (!$a = foo()), en cuyo caso el valor devuelto defoo()es puesto en$a.



Operadores aritméticos

¿Recuerda la aritmética básica de la escuela? Estos funcionan igual que aquellos.

Operadores aritméticos
EjemploNombreResultado
+$aIdentidadConversión de$aaintofloatsegún el caso.
-$aNegaciónOpuesto de$a.
$a + $bAdiciónSuma de$ay$b.
$a - $bSustracciónDiferencia de$ay$b.
$a * $bMultiplicaciónProducto de$ay$b.
$a / $bDivisiónCociente de$ay$b.
$a % $bMóduloResto de$adividido por$b.
$a ** $bExponenciaciónResultado de elevar$aa la potencia$bésima. Introducido en PHP 5.6.

El operador de división ("/") devuelve un valor flotante a menos que los dos operandos sean integers (o strings que se conviertan a integers) y los números sean divisibles, en cuyo caso será devuelto un valor integer.

Los operandos del módulo se convierten en integers (por extracción de la parte decimal) antes del procesamiento.

El resultado del operador módulo%tiene el mismo signo que el dividendo — es decir, el resultado de$a % $btendrá el mismo signo que$a. Por ejemplo:

<?php

echo (5%3)."\n";// muestra 2
echo (5% -3)."\n";// muestra 2
echo (-5%3)."\n";// muestra -2
echo (-5% -3)."\n";// muestra -2

?>

Véase también la página del manual sobrefunciones matemáticas.



Operadores de asignación

El operador básico de asignación es "=". Se podría inclinar a pensar primero que es como un "igual a". No lo es. Realmente significa que el operando de la izquierda se establece con el valor de la expresión de la derecha (es decir, "se define como").

El valor de una expresión de asignación es el valor asignado. Es decir, el valor de "$a = 3" es de 3. Esto permite hacer algunas cosas intrincadas:

<?php

$a
= ($b=4) +5;// ahora $a es igual a 9 y $b se ha establecido en 4.

?>

Además del operador básico de asignación, existen «operadores combinados» para todos los dearitmética binaria, unión de arrays y operadores de strings que permiten usar un valor en una expresión y entonces establecer su valor como el resultado de esa expresión. Por ejemplo:

<?php

$a
=3;
$a+=5;// establece $a en 8, como si se hubiera dicho: $a = $a + 5;
$b="Hola ";
$b.="ahí!";// establece $b en "Hola ahí!", al igual que $b = $b . "ahí!";

?>

Observe que la asignación copia la variable original en la nueva (asignación por valor), por lo que los cambios en una no afectarán a la otra. Esto también puede tener relevancia si se necesita copiar algo como un gran array dentro de un bucle estrecho.

Una excepción al comportamiento usual de la asignación por valor en PHP ocurre conobjects los cuales son asignados por referencia en PHP 5. Los objetos pueden ser explícitamente copiados por medio de la palabra claveclone.

Asignación por referencia

La asignación por referencia también está soportada, utilizando la sintaxis "$var = &$othervar;". Asignación por referencia significa que ambas variables terminan apuntando a los mismos datos y nada es copiado en ninguna parte.

Ejemplo #1 Asignación por referencia

<?php
$a
=3;
$b= &$a;// $b es una referencia para $a

print"$a\n";// muestra 3
print"$b\n";// muestra 3

$a=4;// cambia $a

print"$a\n";// muestra 4
print"$b\n";// muestra 4 también, dado que $b es una referencia para $a, la cual ha
// sido cambiada
?>

Desde PHP 5, el operadornewretorna una referencia automáticamente, así que asignar el resultado denewpor referencia, resulta en un mensajeE_DEPRECATEDen PHP 5.3 y posteriores y un mensajeE_STRICTen versiones anteriores.

Por ejemplo, éste código resultará en una advertencia:

<?php
classC{}

/* La siguiente línea genera el siguiente mensaje de error:
* Deprecated: Assigning the return value of new by reference is deprecated in...
*/
$o= &newC;
?>

Más información sobre referencias y sus usos potenciales se puede encontrar en la sección del manualReferencias Explicadas



Operadores bit a bit

Los operadores bit a bit permiten la evaluación y la manipulación de bits específicos dentro de un integer.

Operadores bit a bit
EjemploNombreResultado
$a & $bAnd (y)Los bits que están activos en ambos$ay$bson activados.
$a | $bOr (o inclusivo)Los bits que están activos ya sea en$ao en$bson activados.
$a ^ $bXor (o exclusivo)Los bits que están activos en$ao en$b, pero no en ambos, son activados.
~ $aNot (no)Los bits que están activos en$ason desactivados, y viceversa.
$a << $bShift left(desplazamiento a izquierda)Desplaza los bits de$a,$bpasos a la izquierda (cada paso quiere decir "multiplicar por dos").
$a >> $bShift right (desplazamiento a derecha)Desplaza los bits de$a,$bpasos a la derecha (cada paso quiere decir "dividir por dos").

El desplazamiento de bits en PHP es aritmético. Los bits desplazados por fuera de cualquiera de los extremos son descartados. Desplazamientos de izquierda tienen ceros desplazados a la derecha mientras que el bit de signo es desplazado fuera a la izquierda, es decir que no se conserva el signo de un operando. Desplazamientos a la derecha tienen copias del bit de signo desplazado a la izquierda, es decir que se conserva el signo de un operando.

Utilice paréntesis para garantizar laprecedenciadeseada. Por ejemplo,$a & $b == trueevalúa la equivalencia y luego el bit a bit, mientras que($a & $b) == trueevalúa el bit a bit y luego la equivalencia.

Si los operandos para los operadores&,|y^son string, la operación se realizará con los valores ASCII de los caracteres que componen dichos string, y el resultado será también un string. En todos los demás casos, ambos operandos seránconvertidos a valores de tipo integery el resultado será también un integer.

Si el operando del operados~es un string, la operación se realizará con valores los ASCII de los caracteres que componen dicho string, y el resultado también será un string; en caso contrario, el operando y el resultado serán tratados como valores de tipo integer.

Ambos operandos y el resultado de lo operadores<<y>>siempre son tratados como valores de tipo integer.

      El ajuste ini error_reporting utiliza valores a nivel de bit,
      lo que ofrece una demostración del mundo real de desactivar
      bits. Para mostrar todos los errores, a excepción de los avisos,
      las instrucciones del archivo php.ini dicen utilizar:
      E_ALL & ~E_NOTICE
     

      Esto funciona iniciando con E_ALL:
      00000000000000000111011111111111
      Luego se toma el valor de E_NOTICE ...
      00000000000000000000000000001000
      ... y se invierte por medio de ~:
      11111111111111111111111111110111
      Finalmente, se utiliza AND (&) para encontrar los bits que se
      activaron en ambos valores:
      00000000000000000111011111110111
     

      Otra forma de lograrlo es mediante XOR (^)
      para encontrar los bits que están activados en sólo el primer valor o en el otro:
      E_ALL ^ E_NOTICE
     

      error_reporting también se puede utilizar para demostrar la activación de bits.
      La forma para mostrar sólo los errores y los errores recuperables es:
      E_ERROR | E_RECOVERABLE_ERROR
     

      Este proceso combina E_ERROR
      00000000000000000000000000000001
      y
      00000000000000000001000000000000
      usando el operador OR (|)
      para obtener los bits activados en cualquiera de estos valores:
      00000000000000000001000000000001
     

Ejemplo #1 Operaciones AND, OR y XOR bit a bit sobre integers

<?php
/*
* Ignore la sección superior,
* es sólo el formateado para hacer la salida más clara.
*/

$format='(%1$2d = %1$04b) = (%2$2d = %2$04b)'
.' %3$s (%4$2d = %4$04b)'."\n";

echo <<<EOH
--------- --------- -- ---------
resultado valor op prueba
--------- --------- -- ---------
EOH;


/*
* Aquí están los ejemplos.
*/

$values= array(0,1,2,4,8);
$test=1+4;

echo
"\n AND bit a bit \n";
foreach (
$valuesas$value) {
$result=$value&$test;
printf($format,$result,$value,'&',$test);
}

echo
"\n OR inclusivo bit a bit \n";
foreach (
$valuesas$value) {
$result=$value|$test;
printf($format,$result,$value,'|',$test);
}

echo
"\n OR exclusivo (XOR) bit a bit \n";
foreach (
$valuesas$value) {
$result=$value^$test;
printf($format,$result,$value,'^',$test);
}
?>

El resultado del ejemplo sería:

 ---------     ---------  -- ---------
 resultado     valor      op prueba
 ---------     ---------  -- ---------
 AND bit a bit
( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101)
( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101)
( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101)
( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101)
( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101)

 OR inclusivo bit a bit
( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101)
( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101)
( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101)
( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101)
(13 = 1101) = ( 8 = 1000) | ( 5 = 0101)

 OR exclusivo (XOR) bit a bit
( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101)
( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101)
( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101)
( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101)
(13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)

Ejemplo #2 Operaciones XOR bit a bit sobre strings

<?php
echo12^9;// Sale '5'

echo"12"^"9";// Sale el caracter de retroceso (ascii 8)
// ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

echo"hallo"^"hello";// Salen los valores ascii #0 #4 #0 #0 #0
// 'a' ^ 'e' = #4

echo2^"3";// Sale 1
// 2 ^ ((int)"3") == 1

echo"2"^3;// Sale 1
// ((int)"2") ^ 3 == 1
?>

Ejemplo #3 Desplazamiento de bits sobre integers

<?php
/*
* Aquí están los ejemplos.
*/

echo"\n--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS POSITIVOS ---\n";

$val=4;
$places=1;
$res=$val>>$places;
p($res,$val,'>>',$places,'copia del bit de signo desplazado hacia el lado izquierdo');

$val=4;
$places=2;
$res=$val>>$places;
p($res,$val,'>>',$places);

$val=4;
$places=3;
$res=$val>>$places;
p($res,$val,'>>',$places,'bits desplazados fuera del lado derecho');

$val=4;
$places=4;
$res=$val>>$places;
p($res,$val,'>>',$places,'mismo resultado que arriba; no se puede desplazar más allá del 0');


echo
"\n--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS NEGATIVOS ---\n";

$val= -4;
$places=1;
$res=$val>>$places;
p($res,$val,'>>',$places,'copia del bit de signo desplazado al lado izquierdo');

$val= -4;
$places=2;
$res=$val>>$places;
p($res,$val,'>>',$places,'bits desplazados fuera del lado derecho');

$val= -4;
$places=3;
$res=$val>>$places;
p($res,$val,'>>',$places,'mismo resultado que arriba; no se puede desplazar más allá del -1');


echo
"\n--- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS POSITIVOS ---\n";

$val=4;
$places=1;
$res=$val<<$places;
p($res,$val,'<<',$places,'ceros rellenan en el lado derecho');

$val=4;
$places= (PHP_INT_SIZE*8) -4;
$res=$val<<$places;
p($res,$val,'<<',$places);

$val=4;
$places= (PHP_INT_SIZE*8) -3;
$res=$val<<$places;
p($res,$val,'<<',$places,'bit de signo resulta desplazado fuera');

$val=4;
$places= (PHP_INT_SIZE*8) -2;
$res=$val<<$places;
p($res,$val,'<<',$places,'bit de signo desplazado fuera del lado izquierdo');


echo
"\n--- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS NEGATIVOS ---\n";

$val= -4;
$places=1;
$res=$val<<$places;
p($res,$val,'<<',$places,'ceros rellenan en el lado derecho');

$val= -4;
$places= (PHP_INT_SIZE*8) -3;
$res=$val<<$places;
p($res,$val,'<<',$places);

$val= -4;
$places= (PHP_INT_SIZE*8) -2;
$res=$val<<$places;
p($res,$val,'<<',$places,'bits desplazados fuera del lado izquierdo, incluyendo el bit de signo');


/*
* Ignore this bottom section,
* it is just formatting to make output clearer.
*/

functionp($res,$val,$op,$places,$note='') {
$format='%0'. (PHP_INT_SIZE*8) ."b\n";

printf("Expression: %d = %d %s %d\n",$res,$val,$op,$places);

echo
" Decimal:\n";
printf(" val=%d\n",$val);
printf(" res=%d\n",$res);

echo
" Binary:\n";
printf(' val='.$format,$val);
printf(' res='.$format,$res);

if (
$note) {
echo
" NOTE:$note\n";
}

echo
"\n";
}
?>

El resultado del ejemplo en equipos de 32 bit sería:


--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS POSITIVOS ---
Expression: 2 = 4 >> 1
 Decimal:
  val=4
  res=2
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000010
 NOTE: copia del bit de signo desplazado hacia el lado izquierdo

Expression: 1 = 4 >> 2
 Decimal:
  val=4
  res=1
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000001

Expression: 0 = 4 >> 3
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: bits desplazados fuera del lado derecho

Expression: 0 = 4 >> 4
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: mismo resultado que arriba; no se puede desplazar más allá del 0


--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS NEGATIVOS ---
Expression: -2 = -4 >> 1
 Decimal:
  val=-4
  res=-2
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111110
 NOTE: copia del bit de signo desplazado al lado izquierdo

Expression: -1 = -4 >> 2
 Decimal:
  val=-4
  res=-1
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111111
 NOTE: bits desplazados fuera del lado derecho

Expression: -1 = -4 >> 3
 Decimal:
  val=-4
  res=-1
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111111
 NOTE: mismo resultado que arriba; no se puede desplazar más allá del -1


--- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS POSITIVOS ---
Expression: 8 = 4 << 1
 Decimal:
  val=4
  res=8
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000001000
 NOTE: ceros rellenan en el lado derecho

Expression: 1073741824 = 4 << 28
 Decimal:
  val=4
  res=1073741824
 Binary:
  val=00000000000000000000000000000100
  res=01000000000000000000000000000000

Expression: -2147483648 = 4 << 29
 Decimal:
  val=4
  res=-2147483648
 Binary:
  val=00000000000000000000000000000100
  res=10000000000000000000000000000000
 NOTE: bit de signo resulta desplazado fuera

Expression: 0 = 4 << 30
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: bit de signo desplazado fuera del lado izquierdo


--- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS NEGATIVOS ---
Expression: -8 = -4 << 1
 Decimal:
  val=-4
  res=-8
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111000
 NOTE: ceros rellenan en el lado derecho

Expression: -2147483648 = -4 << 29
 Decimal:
  val=-4
  res=-2147483648
 Binary:
  val=11111111111111111111111111111100
  res=10000000000000000000000000000000

Expression: 0 = -4 << 30
 Decimal:
  val=-4
  res=0
 Binary:
  val=11111111111111111111111111111100
  res=00000000000000000000000000000000
 NOTE: bits desplazados fuera del lado izquierdo, incluyendo el bit de signo

El resultado del ejemplo en equipos de 64 bit sería:


--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS POSITIVOS ---
Expression: 2 = 4 >> 1
 Decimal:
  val=4
  res=2
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000010
 NOTE: copia del bit de signo desplazado hacia el lado izquierdo

Expression: 1 = 4 >> 2
 Decimal:
  val=4
  res=1
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000001

Expression: 0 = 4 >> 3
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bits desplazados fuera del lado derecho

Expression: 0 = 4 >> 4
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: mismo resultado que arriba; no se puede desplazar más allá del 0


--- DESPLAZAMIENTO DE BITS A LA DERECHA SOBRE ENTEROS NEGATIVOS ---
Expression: -2 = -4 >> 1
 Decimal:
  val=-4
  res=-2
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111110
 NOTE: copia del bit de signo desplazado al lado izquierdo

Expression: -1 = -4 >> 2
 Decimal:
  val=-4
  res=-1
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111111
 NOTE: bits desplazados fuera del lado derecho

Expression: -1 = -4 >> 3
 Decimal:
  val=-4
  res=-1
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111111
 NOTE: mismo resultado que arriba; no se puede desplazar más allá del -1


--- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS POSITIVOS ---
Expression: 8 = 4 << 1
 Decimal:
  val=4
  res=8
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000001000
 NOTE: ceros rellenan en el lado derecho

Expression: 4611686018427387904 = 4 << 60
 Decimal:
  val=4
  res=4611686018427387904
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0100000000000000000000000000000000000000000000000000000000000000

Expression: -9223372036854775808 = 4 << 61
 Decimal:
  val=4
  res=-9223372036854775808
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=1000000000000000000000000000000000000000000000000000000000000000
 NOTE: bit de signo resulta desplazado fuera

Expression: 0 = 4 << 62
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bit de signo desplazado fuera del lado izquierdo


--- DESPLAZAMIENTO DE BITS A LA IZQUIERDA SOBRE ENTEROS NEGATIVOS ---
Expression: -8 = -4 << 1
 Decimal:
  val=-4
  res=-8
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111000
 NOTE: ceros rellenan en el lado derecho

Expression: -9223372036854775808 = -4 << 61
 Decimal:
  val=-4
  res=-9223372036854775808
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1000000000000000000000000000000000000000000000000000000000000000

Expression: 0 = -4 << 62
 Decimal:
  val=-4
  res=0
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bits desplazados fuera del lado izquierdo, incluyendo el bit de signo

Advertencia

Desplazar un integer por valores mayores o iguales al ancho del tipo long integer del sistema resultará en un comportamiento indefinido. En otras palabras, no desplace más de 31 bit en sistemas de 32 bit, y no desplace más de 63 bit en sistemas de 64 bit.

Use funciones de la extensióngmppara manipular a nivel de bit números mayores quePHP_INT_MAX.

Ver tambiénpack(),unpack(),gmp_and(),gmp_or(),gmp_xor(),gmp_testbit(),gmp_clrbit()



Operadores de comparación

Los operadores de comparación, como su nombre lo indica, permiten comparar dos valores. Puede también estar interesado en verlas tablas de comparación de tipos, ya que muestran ejemplos de las varias comparaciones relacionadas con tipos.

Operadores de comparación
EjemploNombreResultado
$a == $bIgualtruesi$aes igual a$bdespués de la manipulación de tipos.
$a === $bIdénticotruesi$aes igual a$b, y son del mismo tipo.
$a != $bDiferentetruesi$ano es igual a$bdespués de la manipulación de tipos.
$a <> $bDiferentetruesi$ano es igual a$bdespués de la manipulación de tipos.
$a !== $bNo idénticotruesi$ano es igual a$b, o si no son del mismo tipo.
$a < $bMenor quetruesi$aes estrictamente menor que$b.
$a > $bMayor quetruesi$aes estrictamente mayor que$b.
$a <= $bMenor o igual quetruesi$aes menor o igual que$b.
$a >= $bMayor o igual quetruesi$aes mayor o igual que$b.
$a <=> $bNave espacialUnintegermenor que, igual a, o mayor que cero cuando$aes respectivamente menor que, igual a, o mayor que$b. Disponible a partir de PHP 7.
$a ?? $b ?? $cFusión de nullEl primer operando de izquierda a derecha que exista y no seanull.nullsi no hay valores definidos y no sonnull. Disponible a partir de PHP 7.

Si se compara un número con un string o la comparación implica strings numéricos, entonces cada string esconvertido en un númeroy la comparación realizada numéricamente. Estas reglas también se aplican a la sentenciaswitch. La conversión de tipo no tiene lugar cuando la comparación es === o !== ya que esto involucra comparar el tipo así como el valor.

<?php
var_dump
(0=="a");// 0 == 0 -> true
var_dump("1"=="01");// 1 == 1 -> true
var_dump("10"=="1e1");// 10 == 10 -> true
var_dump(100=="1e2");// 100 == 100 -> true

switch ("a") {
case
0:
echo
"0";
break;
case
"a":// nunca alcanzado debido a que "a" ya ha coincidido con 0
echo"a";
break;
}
?>
<?php
// Integers
echo1<=>1;// 0
echo1<=>2;// -1
echo2<=>1;// 1

// Floats
echo1.5<=>1.5;// 0
echo1.5<=>2.5;// -1
echo2.5<=>1.5;// 1

// Strings
echo"a"<=>"a";// 0
echo"a"<=>"b";// -1
echo"b"<=>"a";// 1

echo"a"<=>"aa";// -1
echo"zz"<=>"aa";// 1

// Arrays
echo [] <=> [];// 0
echo [1,2,3] <=> [1,2,3];// 0
echo [1,2,3] <=> [];// 1
echo [1,2,3] <=> [1,2,1];// 1
echo [1,2,3] <=> [1,2,4];// -1

// Objects
$a= (object) ["a"=>"b"];
$b= (object) ["a"=>"b"];
echo
$a<=>$b;// 0

$a= (object) ["a"=>"b"];
$b= (object) ["a"=>"c"];
echo
$a<=>$b;// -1

$a= (object) ["a"=>"c"];
$b= (object) ["a"=>"b"];
echo
$a<=>$b;// 1

// only values are compared
$a= (object) ["a"=>"b"];
$b= (object) ["b"=>"b"];
echo
$a<=>$b;// 1

?>

Para varios tipos, la comparación se realiza de acuerdo a la siguiente tabla (en orden).

La comparación con varios tipos
Tipo de operando 1Tipo de operando 2Resultado
nullostringstringConviertenullen "", comparación numérica o léxica
boolonullcualquieraConvierte ambos lados abool,false<true
objectobjectLas clases internas pueden definir su propia comparación, diferentes clases son incomparables, la misma clase - comparan propiedades en la misma forma que los arrays (PHP 4), PHP 5 tiene su propiaexplicación
string,resourceonumberstring,resourceonumberTraducir las cadenas y recursos a números, matemática usual
arrayarrayUn array con menos elementos es menor, si una clave del operando 1 no se encuentra en el operando 2 entonces los arrays son incomparables, de otra forma - compara valor por valor (ver el siguiente ejemplo)
objectcualquieraobjectes siempre mayor
arraycualquieraarrayes siempre mayor

Ejemplo #1 Comparación boolean/null

<?php
// Booleanos y null son comparados siempre coomo bool
var_dump(1==TRUE);// TRUE - same as (bool)1 == TRUE
var_dump(0==FALSE);// TRUE - same as (bool)0 == FALSE
var_dump(100<TRUE);// FALSE - same as (bool)100 < TRUE
var_dump(-10<FALSE);// FALSE - same as (bool)-10 < FALSE
var_dump(min(-100, -10,NULL,10,100));// NULL - (bool)NULL < (bool)-100 is FALSE < TRUE
?>

Ejemplo #2 Transcripción de la comparación estándar de arrays

<?php
// Arrays son comparados de esta forma con los operadores de comparación estándar
functionstandard_array_compare($op1,$op2)
{
if (
count($op1) <count($op2)) {
return -
1;// $op1 < $op2
} elseif (count($op1) >count($op2)) {
return
1;// $op1 > $op2
}
foreach (
$op1as$key=>$val) {
if (!
array_key_exists($key,$op2)) {
return
null;// uncomparable
} elseif ($val<$op2[$key]) {
return -
1;
} elseif (
$val>$op2[$key]) {
return
1;
}
}
return
0;// $op1 == $op2
}
?>

Ver tambiénstrcasecmp(),strcmp(),operadores de array, y la sección del manual sobretipos.

Advertencia

Comparación de números de punto flotante

Debido a la forma en que son representados internamente losfloats, no se deben probar por igualdad dosfloats.

Ver la documentación defloatpara más información.

Operador ternario

Otro operador condicional es el operador "?:" (o ternario).

Ejemplo #3 Asignación de un valor predeterminado

<?php
// Ejemplo de uso para: Operador Ternario
$action= (empty($_POST['action'])) ?'default':$_POST['action'];

// Lo anterior es idéntico a esta sentencia if/else
if (empty($_POST['action'])) {
$action='default';
} else {
$action=$_POST['action'];
}

?>
La expresión(expr1) ? (expr2) : (expr3)evalúa aexpr2siexpr1se evalúa comotruey aexpr3siexpr1se evalúa comofalse.

A partir de PHP 5.3, es posible dejar de lado la parte media del operador ternario. La expresiónexpr1 ?: expr3retornaexpr1siexpr1se evalúa comotrueyexpr3si es de otra manera.

Nota:Por favor note que el operador ternario es una expresión, y que no evalúa a una variable, sino al resultado de una expresión. Esto es importante saberlo si se desea retornar una variable por referencia. La sentenciareturn $var == 42 ? $a : $b;en una función con retorno-por-referencia no funcionará por lo que se ha mencionado y una advertencia es generada en versiones posteriores de PHP.

Nota:

Es recomendable evitar el "apilamiento" expresiones ternarias. El comportamiento de PHP al utilizar más de un operador ternario en una única sentencia no es evidente:

Ejemplo #4 Comportamiento Ternario poco obvio

<?php
// a primera vista, lo siguiente parece tener la salida de 'true'
echo (true?'true':false?'t':'f');

// sin embargo, la salida real de lo anterior es 't'
// esto se debe a que las expresiones ternarias se evalúan de izquierda a derecha

// la siguiente es una versión más obvia del mismo código anterior
echo ((true?'true':false) ?'t':'f');

// aquí, se puede ver que la primera expresión es evaluada como 'true', que
// a su vez se evalúa como (bool)true, retornando así la rama verdadera de la
// segunda expresión ternaria.
?>

Null Coalescing Operator

Further exists the "??" (or null coalescing) operator.

Ejemplo #5 Assigning a default value

<?php
// Example usage for: Null Coalesce Operator
$action=$_POST['action'] ??'default';

// The above is identical to this if/else statement
if (isset($_POST['action'])) {
$action=$_POST['action'];
} else {
$action='default';
}

?>
The expression(expr1) ?? (expr2)evaluates toexpr2ifexpr1isnull, andexpr1otherwise.

In particular, this operator does not emit a notice or warning if the left-hand side value does not exist, just likeisset(). This is especially useful on array keys.

Nota:Please note that the null coalescing operator is an expression, and that it doesn't evaluate to a variable, but to the result of an expression. This is important to know if you want to return a variable by reference. The statementreturn $foo ?? $bar;in a return-by-reference function will therefore not work and a warning is issued.

Nota:

Please note that the null coalescing operator allows for simple nesting:

Ejemplo #6 Nesting null coalescing operator

<?php

$foo
=null;
$bar=null;
$baz=1;
$qux=2;

echo
$foo??$bar??$baz??$qux;// outputs 1

?>



Operadores de control de errores

PHP soporta un operador de control de errores: el signo de arroba (@). Cuando se antepone a una expresión en PHP, cualquier mensaje de error que pueden ser generado por esa expresión será ignorado.

Si se ha establecido una función controladora de errores personalizada conset_error_handler()entonces todavía será llamada, pero este controlador de errores personalizado puede (y debe) llamar aerror_reporting()el cual devolverá 0 cuando la llamada que provocó el error fue precedida por el signo @.

Si la propiedadtrack_errorsestá activada, cualquier mensaje de error generado por la expresión será guardada en la variable$php_errormsg. Esta variable se sobrescribe en cada error, así que se debe comprobar antes si se desea utilizar.

<?php
/* Error intencional de archivo */
$my_file= @file('non_existent_file') or
die (
"La apertura de archivo ha fallado: el error fue '$php_errormsg'");

// esto funciona con cualquier expresión, no solo con funciones:
$value= @$cache[$key];
// no producirá una anotación si el índice $key no existe.

?>

Nota:El operador @ trabaja sólo sobreexpresiones. Una simple regla de oro es: si se puede tomar el valor de algo, entonces se le puede anteponer el operador @. Por ejemplo, puede anteponerse a variables, a llamadas a funciones eincludes, constantes y así sucesivamente. No puede anteponerse a definiciones de función o clase, ni a estructuras condicionales comoifyforeach, y así sucesivamente.

Ver tambiénerror_reporting()y la sección del manual sobrefunciones de Manejo de Errores y Registros.

Advertencia

En la actualidad, el operador de prefijo "@" para control de errores deshabilitará incluso el reporte de errores en casos de fallos críticos que terminarán la ejecución del script. Entre otras cosas, esto quiere decir que si se usa "@" para eliminar los errores de una cierta función y ésta no se encuentra disponible o ha sido escrita de forma incorrecta, el script se detendrá en ese punto sin indicación de por qué.



Operadores de ejecución

PHP soporta un operador de ejecución: las comillas invertidas (``). ¡Note que estas no son las comillas sencillas! PHP intentará ejecutar el contenido entre las comillas invertidas como si se tratara de un comando del shell; la salida será retornada (es decir, no será simplemente volcada como salida; puede ser asignada a una variable). El uso del operador de comillas invertidas es idéntico al deshell_exec().

<?php
$output
= `ls -al`;
echo
"<pre>$output</pre>";
?>

Nota:

El operador de comillas invertidas se deshabilita cuandoshell_exec()esta desactivado.

Nota:

A diferencia de otros lenguajes, las comillas invertidas no tienen un significa especial dentro de string entre comillas dobles.

Vea también la sección del manual sobrefunciones de ejecución de programas,popen()proc_open()yUsando PHP desde la línea de comandos.



Operadores de incremento/decremento

PHP soporta operadores estilo C de pre- y post-incremento y decremento.

Nota:Los operadores de incremento/decremento solamente afectan a números y strings. Los arrays, objects y resources no se ven afectados. Decrementar valoresnulltampoco tiene efecto, pero incrementarlos entonces resulta en1.

Operadores de incremento/decremento
EjemploNombreEfecto
++$aPre-incrementoIncrementa$aen uno, y luego retorna$a.
$a++Post-incrementoRetorna$a, y luego incrementa$aen uno.
--$aPre-decrementoDecrementa$aen uno, luego retorna$a.
$a--Post-decrementoRetorna$a, luego decrementa$aen uno.

Aquí hay un script simple de ejemplo:

<?php
echo"<h3>Postincremento</h3>";
$a=5;
echo
"Debe ser 5: ".$a++ ."<br />\n";
echo
"Debe ser 6: ".$a."<br />\n";

echo
"<h3>Preincremento</h3>";
$a=5;
echo
"Debe ser 6: ". ++$a."<br />\n";
echo
"Debe ser 6: ".$a."<br />\n";

echo
"<h3>Postdecremento</h3>";
$a=5;
echo
"Debe ser 5: ".$a-- ."<br />\n";
echo
"Debe ser 4: ".$a."<br />\n";

echo
"<h3>Predecremento</h3>";
$a=5;
echo
"Debe ser 4: ". --$a."<br />\n";
echo
"Debe ser 4: ".$a."<br />\n";
?>

PHP sigue la convención de Perl cuando trabaja con operaciones aritméticas sobre variables de caracteres y no la de C. Por ejemplo, en PHP y Perl$a = 'Z'; $a++;convierte$aen'AA', mientras que en Ca = 'Z'; a++;convierteaen'['(el valor ASCII de'Z'es 90, el valor ASCII de'['es 91). Nótese que las variables de caracteres pueden ser incrementadas pero no decrementadas y aun así sólo caracteres y dígitos de ASCII puro (a-z, A-Z y 0-9) están soportados. Incrementar o decrementar otras variables de caracteres no tiene efecto, el string original no se modifica.

Ejemplo #1 Operaciones aritméticas sobre variables de caracteres

<?php
echo'== Letras =='.PHP_EOL;
$s='W';
for (
$n=0;$n<6;$n++) {
echo ++
$s.PHP_EOL;
}
// Los caracteres de dígitos tienen un comportamiento diferente
echo'== Dígitos =='.PHP_EOL;
$d='A8';
for (
$n=0;$n<6;$n++) {
echo ++
$d.PHP_EOL;
}
$d='A08';
for (
$n=0;$n<6;$n++) {
echo ++
$d.PHP_EOL;
}
?>

El resultado del ejemplo sería:

== Letras ==
X
Y
Z
AA
AB
AC
== Dígitos ==
A9
B0
B1
B2
B3
B4
A09
A10
A11
A12
A13
A14

Incrementar o decrementar booleanos no tiene efecto.



Operadores lógicos

Operadores lógicos
EjemploNombreResultado
$a and $bAnd (y)truesi tanto$acomo$bsontrue.
$a or $bOr (o inclusivo)truesi cualquiera de$ao$bestrue.
$a xor $bXor (o exclusivo)truesi$ao$bestrue, pero no ambos.
! $aNot (no)truesi$ano estrue.
$a && $bAnd (y)truesi tanto$acomo$bsontrue.
$a || $bOr (o inclusivo)truesi cualquiera de$ao$bestrue.

La razón para tener las dos variaciones diferentes de los operadores "and" y "or" es que ellos operan con precedencias diferentes. (VerPrecedencia de operadores.)

Ejemplo #1 Los operadores lógicos ilustrados

<?php

// --------------------
// foo() nunca será llamado ya que los operadores están en cortocircuito

$a= (false&&foo());
$b= (true||foo());
$c= (falseandfoo());
$d= (trueorfoo());

// --------------------
// "||" tiene una precedencia mayor que "or"

// El resultado de la expresión (false || true) es asignado a $e
// Actúa como: ($e = (false || true))
$e=false||true;

// La constante false es asignada a $f antes de que suceda la operación "or"
// Actúa como: (($f = false) or true)
$f=falseortrue;

var_dump($e,$f);

// --------------------
// "&&" tiene una precedencia mayor que "and"

// El resultado de la expresión (true && false) es asignado a $g
// Actúa como: ($g = (true && false))
$g=true&&false;

// La constante true es asignada a $h antes de que suceda la operación "and"
// Actúa como: (($h = true) and false)
$h=trueandfalse;

var_dump($g,$h);
?>

El resultado del ejemplo sería algo similar a:

bool(true)
bool(false)
bool(false)
bool(true)


Operadores para strings

Existen dos operadores para datos tipostring. El primero es el operador de concatenación ('.'), el cual retorna el resultado de concatenar sus argumentos derecho e izquierdo. El segundo es el operador de asignación sobre concatenación ('.='), el cual añade el argumento del lado derecho al argumento en el lado izquierdo. Por favor consulteOperadores de asignaciónpara más información.

<?php
$a
="Hello ";
$b=$a."World!";// ahora $b contiene "Hello World!"

$a="Hello ";
$a.="World!";// ahora $a contiene "Hello World!"
?>

Ver también las secciones del manual sobre eltipo stringy lasfunciones de strings.



Operadores para arrays

Operadores para arrays
EjemploNombreResultado
$a + $bUniónUnión de$ay$b.
$a == $bIgualdadtruesi$ai$btienen las mismas parejas clave/valor.
$a === $bIdentidadtruesi$ay$btienen las mismas parejas clave/valor en el mismo orden y de los mismos tipos.
$a != $bDesigualdadtruesi$ano es igual a$b.
$a <> $bDesigualdadtruesi$ano es igual a$b.
$a !== $bNo-identidadtruesi$ano es idéntica a$b.

El operador+devuelve el array del lado derecho añadido al array del lado izquierdo; para las claves que existan en ambos arrays, serán utilizados los elementos del array de la izquierda y serán ignorados los elementos correspondientes del array de la derecha.

<?php
$a
= array("a"=>"apple","b"=>"banana");
$b= array("a"=>"pear","b"=>"strawberry","c"=>"cherry");

$c=$a+$b;// Unión de $a y $b
echo"Unión de \$a y \$b: \n";
var_dump($c);

$c=$b+$a;// Unión de $b y $a
echo"Unión de \$b y \$a: \n";
var_dump($c);

$a+=$b;// Unión de $a += $b es $a y $b
echo"Unión de \$a += \$b: \n";
var_dump($a);
?>
Cuando sea ejecutado, este script producirá la siguiente salida:
Unión de $a y $b:
array(3) {
  ["a"]=>
  string(5) "apple"
  ["b"]=>
  string(6) "banana"
  ["c"]=>
  string(6) "cherry"
}
Unión de $b y $a:
array(3) {
  ["a"]=>
  string(4) "pear"
  ["b"]=>
  string(10) "strawberry"
  ["c"]=>
  string(6) "cherry"
}
Unión de $a += $b:
array(3) {
  'a' =>
  string(5) "apple"
  'b' =>
  string(6) "banana"
  'c' =>
  string(6) "cherry"
}

Los elementos de los arrays son iguales para la comparación si éstos tienen la misma clave y valor.

Ejemplo #1 Comparando arrays

<?php
$a
= array("apple","banana");
$b= array(1=>"banana","0"=>"apple");

var_dump($a==$b);// bool(true)
var_dump($a===$b);// bool(false)
?>

Ver también las secciones del manual sobre eltipo arrayyfunciones de arrays.



Operadores de tipo

instanceofse utiliza para determinar si una variable de PHP es un objeto instanciado de una ciertaclase:

Ejemplo #1 Utilizandoinstanceofcon clases

<?php
classMyClass
{
}

class
NotMyClass
{
}
$a= newMyClass;

var_dump($ainstanceofMyClass);
var_dump($ainstanceofNotMyClass);
?>

El resultado del ejemplo sería:

bool(true)
bool(false)

instanceoftambién se puede utilizar para determinar si una variable es un objeto instanciado de una clase que hereda de una clase padre:

Ejemplo #2 Utilizandoinstanceofcon clases heredadas

<?php
classParentClass
{
}

class
MyClassextendsParentClass
{
}

$a= newMyClass;

var_dump($ainstanceofMyClass);
var_dump($ainstanceofParentClass);
?>

El resultado del ejemplo sería:

bool(true)
bool(true)

Para comprobar si un objetonoes una instancia de una clase, se puede usar eloperador lógiconot.

Ejemplo #3 Utilizandoinstanceofpara verificar si un objetonoes una instancia de una clase

<?php
classMyClass
{
}

$a= newMyClass;
var_dump(!($ainstanceofstdClass));
?>

El resultado del ejemplo sería:

bool(true)

Finalmente,instanceoftambién se puede utilizar para determinar si una variable es un objeto instanciado de una clase que implementa unainterface:

Ejemplo #4 Utilizandoinstanceofpara la clase

<?php
interfaceMyInterface
{
}

class
MyClassimplementsMyInterface
{
}

$a= newMyClass;

var_dump($ainstanceofMyClass);
var_dump($ainstanceofMyInterface);
?>

El resultado del ejemplo sería:

bool(true)
bool(true)

Aunqueinstanceofse utiliza generalmente con un nombre de clase literal, también puede ser utilizado con otro objeto o una variable string:

Ejemplo #5 Utilizandoinstanceofcon otras variables

<?php
interfaceMyInterface
{
}

class
MyClassimplementsMyInterface
{
}

$a= newMyClass;
$b= newMyClass;
$c='MyClass';
$d='NotMyClass';

var_dump($ainstanceof$b);// $b is an object of class MyClass
var_dump($ainstanceof$c);// $c is a string 'MyClass'
var_dump($ainstanceof$d);// $d is a string 'NotMyClass'
?>

El resultado del ejemplo sería:

bool(true)
bool(true)
bool(false)

instanceof no lanza ningún error si la variable que está siendo comprobada no es un objeto, simplemente devuelvefalse. Las constantes, sin embargo, no está permitidas.

Ejemplo #6 Usarinstanceofpara comprobar otras variables

<?php
$a
=1;
$b=NULL;
$c=imagecreate(5,5);
var_dump($ainstanceofstdClass);// $a es un entero
var_dump($binstanceofstdClass);// $b es NULL
var_dump($cinstanceofstdClass);// $c es un recurso
var_dump(FALSEinstanceofstdClass);
?>

El resultado del ejemplo sería:

bool(false)
bool(false)
bool(false)
PHP Fatal error:  instanceof expects an object instance, constant given

Hay algunas trampas a tener en cuenta. Antes de versión de PHP 5.1.0,instanceofllamaría a__autoload()si el nombre de clase no existía. Además, si la clase no estaba cargada, un error fatal ocurriría. Esto se puede solucionar mediante una referencia de clase dinámica o una variable string que contenga el nombre de la clase:

Ejemplo #7 Evitando búsquedas del nombre de clase y errores fatales coninstanceofen PHP 5.0

<?php
$d
='NotMyClass';
var_dump($ainstanceof$d);// aquí no hay error fatal
?>

El resultado del ejemplo sería:

bool(false)

El operadorinstanceoffue introducido en PHP 5. Antes de esta época se utilizabais_a(), pero desde entoncesis_a()se ha quedado obsoleto en favor deinstanceof. Tenga en cuenta que a partir de PHP 5.3.0,is_a()ya no está obsoleto.

Ver tambiénget_class()yis_a().




Estructuras de Control

Tabla de contenidos


Introducción

Todo script PHP está construido según una serie de sentencias. Una sentencia puede ser una asignación, una llamada de función, un ciclo, una sentencia condicional o incluso una sentencia que no hace nada (una sentencia vacía). Las sentencias generalmente finalizan con un punto y coma. Adicionalmente, las sentencias pueden agruparse en un conjunto de sentencias, encapsulándolas entre corchetes. Un grupo de sentencias es una sentencia por sí misma también. Los diferentes tipos de sentencias son descritos en este capítulo.



if

(PHP 4, PHP 5, PHP 7, PHP 8)

El constructorifes una de las características más importantes de muchos lenguajes, incluido PHP. Permite la ejecución condicional de fragmentos de código. PHP dispone de una estructuraifque es similar a la de C:

if (expr)
  sentencia

Como se describe enla sección sobre expresiones, laexpresiónes evaluada a su valor booleano. Si laexpresiónse evalúa comotrue, PHP ejecutará lasentenciay si se evalúa comofalsela ignorará. Más información sobre qué valores evalúan comofalsese puede encontrar en la sección'Convirtiendo a booleano'.

El siguiente ejemplo mostraríaa es mayor que bsi$aes mayor que$b:

<?php
if ($a>$b) {
echo
"a es mayor que b";
}
?>

A menudo se desea tener más de una sentencia para ser ejecutada condicionalmente. Por supuesto, no hay necesidad de envolver cada sentencia con una cláusulaif. En cambio, se pueden agrupar varias sentencias en un grupo de sentencias. Por ejemplo, este código mostraríaa es mayor que bsi$aes mayor que$by entonces asignaría el valor de$aa$b:

<?php
if ($a>$b) {
echo
"a es mayor que b";
$b=$a;
}
?>

Las sentenciasifpueden anidarse dentro de otra sentenciasifinfinitamente, lo cual provee completa flexibilidad para la ejecución condicional de diferentes partes del programa.



else

(PHP 4, PHP 5, PHP 7, PHP 8)

Con frecuencia se desea ejecutar una sentencia si una determinada condición se cumple y una sentencia diferente si la condición no se cumple. Esto es para lo que sirveelse. Elelseextiende una sentenciaifpara ejecutar una sentencia en caso que la expresión en la sentenciaifse evalúe comofalse. Por ejemplo, el siguiente código deberá mostrara es mayor que bsi$aes mayor que$bya NO es mayor que ben el caso contrario:

<?php
if ($a>$b) {
echo
"a es mayor que b";
} else {
echo
"a NO es mayor que b";
}
?>
La sentenciaelsesólo es ejecutada si la expresiónifes evaluada comofalsey si hay algunas expresioneselseif- sólo se ejecuta si también todas son evaluadas comofalse(verelseif).



elseif/else if

(PHP 4, PHP 5, PHP 7, PHP 8)

elseif, como su nombre lo sugiere, es una combinación deifyelse. Del mismo modo queelse, extiende una sentenciaifpara ejecutar una sentencia diferente en caso que la expresióniforiginal se evalúe comofalse. Sin embargo, a diferencia deelse, esa expresión alternativa sólo se ejecutará si la expresión condicional delelseifse evalúa comotrue. Por ejemplo, el siguiente código debe mostrara es mayor que b,a es igual que boa es menor que b:

<?php
if ($a>$b) {
echo
"a es mayor que b";
} elseif (
$a==$b) {
echo
"a es igual que b";
} else {
echo
"a es menor que b";
}
?>

Puede haber varioselseifdentro de la misma sentenciaif. La primera expresiónelseif(si hay alguna) que se evalúe comotruesería ejecutada. En PHP también se puede escribir 'else if' (en dos palabras) y el comportamiento sería idéntico al de 'elseif' (en una sola palabra). El significado sintáctico es ligeramente diferente (si se está familiarizado con C, este es el mismo comportamiento) pero la conclusión es que ambos resultarían tener exactamente el mismo comportamiento.

La sentenciaelseifes ejecutada solamente si la expresiónifprecedente y cualquiera de las expresioneselseifprecedentes son evaluadas comofalse, y la expresiónelseifactual se evalúa comotrue.

Nota:Tenga en cuenta queelseifyelse ifserán considerados exactamente iguales sólamente cuando se utilizan llaves como en el ejemplo anterior. Al utilizar los dos puntos para definir las condicionesif/elseif, no debe separarseelse ifen dos palabras o PHP fallará con un error del interprete.

<?php

/* Método incorrecto: */
if ($a>$b):
echo
$a." es mayor que ".$b;
else if (
$a==$b):// No compilará
echo"La línea anterior provoca un error del interprete.";
endif;


/* Método correcto: */
if ($a>$b):
echo
$a." es mayor que ".$b;
elseif (
$a==$b):// Tenga en cuenta la combinación de las palabras.
echo$a." igual ".$b;
else:
echo
$a." no es ni mayor ni igual a ".$b;
endif;

?>



Sintaxis alternativa de estructuras de control

(PHP 4, PHP 5, PHP 7, PHP 8)

PHP ofrece una sintaxis alternativa para algunas de sus estructuras de control, a saber:if,while,for,foreach, yswitch. En cada caso, la forma básica de la sintaxis alternativa es cambiar la llave de apertura por dos puntos (:) y la llave de cierre porendif;,endwhile;,endfor;,endforeach;, oendswitch;, respectivamente.

<?phpif ($a==5):?>
A es igual a 5
<?phpendif;?>

En el ejemplo anterior, el bloque HTML "A es igual a 5" está anidado dentro de una sentenciaifescrita en la sintaxis alternativa. El bloque HTML se mostraría solamente si$aes igual a 5.

La sintaxis alternativa también se aplica aelseyelseif. La siguiente es una estructuraifconelseifyelseen el formato alternativo:

<?php
if ($a==5):
echo
"a igual 5";
echo
"...";
elseif (
$a==6):
echo
"a igual 6";
echo
"!!!";
else:
echo
"a no es 5 ni 6";
endif;
?>

Nota:

No se admite la mezcla de sintaxis en el mismo bloque de control.

Advertencia

Cualquier salida (incluyendo espacios en blanco) entre una sentenciaswitchy el primercaseresultará en un error de sintaxis. Por ejemplo, esto no es válido:

<?phpswitch ($foo):?>
<?phpcase1:?>
...
<?phpendswitch?>

Mientras que lo siguinte es válido, ya que la nueva línea al final después de la sentenciaswitches considerada como parte del?>de cierre, no generando nada entre elswitchy elcase:

<?phpswitch ($foo):?>
<?php
case1:?>
...
<?phpendswitch?>

Véase tambiénwhile,foreifpara más ejemplos.



while

(PHP 4, PHP 5, PHP 7, PHP 8)

Los bucleswhileson el tipo más sencillo de bucle en PHP. Se comportan igual que su contrapartida en C. La forma básica de una sentenciawhilees:

while (expr)
    sentencia

El significado de una sentenciawhilees simple. Le dice a PHP que ejecute las sentencias anidadas, tanto como la expresiónwhilese evalúe comotrue. El valor de la expresión es verificado cada vez al inicio del bucle, por lo que incluso si este valor cambia durante la ejecución de las sentencias anidadas, la ejecución no se detendrá hasta el final de la iteración (cada vez que PHP ejecuta las sentencias contenidas en el bucle es una iteración). A veces, si la expresiónwhilese evalúa comofalsedesde el principio, las sentencias anidadas no se ejecutarán ni siquiera una vez.

Al igual que con la sentenciaif, se pueden agrupar varias instrucciones dentro del mismo buclewhilerodeando un grupo de sentencias con corchetes, o utilizando la sintaxis alternativa:

while (expr):
    sentencias
    ...
endwhile;

Los siguientes ejemplos son idénticos y ambos presentan los números del 1 al 10:

<?php
/* ejemplo 1 */

$i=1;
while (
$i<=10) {
echo
$i++;/* el valor presentado sería
$i antes del incremento
(post-incremento) */
}

/* ejemplo 2 */

$i=1;
while (
$i<=10):
echo
$i;
$i++;
endwhile;
?>



do-while

(PHP 4, PHP 5, PHP 7, PHP 8)

Los buclesdo-whileson muy similares a los bucleswhile, excepto que la expresión verdadera es verificada al final de cada iteración en lugar que al principio. La diferencia principal con los bucleswhilees que está garantizado que corra la primera iteración de un bucledo-while(la expresión verdadera sólo es verificada al final de la iteración), mientras que no necesariamente va a correr con un buclewhileregular (la expresión verdadera es verificada al principio de cada iteración, si se evalúa comofalsejusto desde el comienzo, la ejecución del bucle terminaría inmediatamente).

Hay una sola sintaxis para buclesdo-while:

<?php
$i
=0;
do {
echo
$i;
} while (
$i>0);
?>

El bucle de arriba se ejecutaría exactamente una sola vez, ya que después de la primera iteración, cuando la expresión verdadera es verificada, se evalúa comofalse($ino es mayor que 0) y termina la ejecución del bucle.

Los usuarios avanzados de C pueden estar familiarizados con un uso distinto del bucledo-while, para permitir parar la ejecución en medio de los bloques de código, mediante el encapsulado condo-while(0), y utilizando la sentenciabreak. El siguiente fragmento de código demuestra esto:

<?php
do {
if (
$i<5) {
echo
"i no es lo suficientemente grande";
break;
}
$i*=$factor;
if (
$i<$minimum_limit) {
break;
}
echo
"i está bien";

/* procesar i */

} while (0);
?>

No se preocupe si no se entiende esto completamente o en absoluto. Se pueden codificar scripts e incluso scripts potentes sin usar esta 'característica'. Desde PHP 5.3.0, es posible utilizar el operadorgotoen lugar de este hack.



for

(PHP 4, PHP 5, PHP 7, PHP 8)

Los buclesforson los más complejos en PHP. Se comportan como sus homólogos en C. La sintaxis de un buclefores:

for (expr1; expr2; expr3)
    sentencia

La primera expresión (expr1) es evaluada (ejecutada) una vez incondicionalmente al comienzo del bucle.

En el comienzo de cada iteración, se evalúaexpr2. Si se evalúa comotrue, el bucle continúa y se ejecutan la/sy sentencia/s anidada/s. Si se evalúa comofalse, finaliza la ejecución del bucle.

Al final de cada iteración, se evalúa (ejecuta)expr3.

Cada una de las expresiones puede estar vacía o contener múltiples expresiones separadas por comas. Enexpr2, todas las expresiones separadas por una coma son evaluadas, pero el resultado se toma de la última parte. Queexpr2esté vacía significa que el bucle debería ser corrido indefinidamente (PHP implícitamente lo considera comotrue, como en C). Esto puede no ser tan inútil como se pudiera pensar, ya que muchas veces se debe terminar el bucle usando una sentencia condicionalbreaken lugar de utilizar la expresión verdadera delfor.

Considere los siguientes ejemplos. Todos ellos muestran los números del 1 al 10:

<?php
/* ejemplo 1 */

for ($i=1;$i<=10;$i++) {
echo
$i;
}

/* ejemplo 2 */

for ($i=1; ;$i++) {
if (
$i>10) {
break;
}
echo
$i;
}

/* ejemplo 3 */

$i=1;
for (; ; ) {
if (
$i>10) {
break;
}
echo
$i;
$i++;
}

/* ejemplo 4 */

for ($i=1,$j=0;$i<=10;$j+=$i, print$i,$i++);
?>

Por supuesto, el primer ejemplo parece ser el mejor (o quizás el cuarto), pero se puede observar que la posibilidad de usar expresiones vacías en los buclesforresulta útil en muchas ocasiones.

PHP también admite la sintaxis alternativa de los dos puntos para buclesfor.

for (expr1; expr2; expr3):
    sentencia
    ...
endfor;

Es una cosa común a muchos usuarios iterar por medio de arrays como en el siguiente ejemplo.

<?php
/*
* Este es un array con algunos datos que se quieren modificar
* cuando se recorra el bucle for.
*/
$people= array(
array(
'name'=>'Kalle','salt'=>856412),
array(
'name'=>'Pierre','salt'=>215863)
);

for(
$i=0;$i<count($people); ++$i) {
$people[$i]['salt'] =mt_rand(000000,999999);
}
?>

El código anterior puede ser lento, debido a que el tamaño del array se capta en cada iteración. Dado que el tamaño nunca cambia, el bucle puede ser fácilmente optimizado mediante el uso de una variable intermedia para almacenar el tamaño en lugar de llamar repetidamente acount():

<?php
$people
= array(
array(
'name'=>'Kalle','salt'=>856412),
array(
'name'=>'Pierre','salt'=>215863)
);

for(
$i=0,$size=count($people);$i<$size; ++$i) {
$people[$i]['salt'] =mt_rand(000000,999999);
}
?>



foreach

(PHP 4, PHP 5, PHP 7, PHP 8)

El constructorforeachproporciona un modo sencillo de iterar sobre arrays.foreachfunciona sólo sobre arrays y objetos, y emitirá un error al intentar usarlo con una variable de un tipo diferente de datos o una variable no inicializada. Existen dos sintaxis:

foreach (expresión_array as $valor)
    sentencias
foreach (expresión_array as $clave => $valor)
    sentencias

La primera forma recorre el array dado porexpresión_array. En cada iteración, el valor del elemento actual se asigna a$valory el puntero interno del array avanza una posición (así en la próxima iteración se estará observando el siguiente elemento).

La segunda forma además asigna la clave del elemento actual a la variable$claveen cada iteración.

También es posiblepersonalizar la iteración de objetos.

Nota:

En PHP 5, cuandoforeachinicia su ejecución, el puntero interno del array se pone automáticamente en el primer elemento del array. Esto significa que no es necesario llamar la funciónreset()antes de un bucleforeach.

Ya queforeachdepende el puntero de array interno en PHP 5, cambiar éste dentro del bucle puede conducir a un comportamiento inesperado.

En PHP 7,foreachno utiliza el puntero interno del array.

Para poder modificar directamente los elementos del array dentro de bucle, se ha de anteponer & a$valor. En este caso el valor será asignado porreferencia.

<?php
$array
= array(1,2,3,4);
foreach (
$arrayas &$valor) {
$valor=$valor*2;
}
// $array ahora es array(2, 4, 6, 8)
unset($valor);// rompe la referencia con el último elemento
?>

Advertencia

La referencia del$valory el último elemento del array permanecen aún después del bucleforeach. Se recomienda destruirlos conunset(). De lo contrario, se experimentará el siguiente funcionamiento:

<?php
$array
= array(1,2,3,4);
foreach (
$arrayas &$valor) {
$valor=$valor*2;
}
// $array ahora es array(2, 4, 6, 8)

// sin unset($valor), $valor aún es una referencia al último elemento: $array[3]

foreach ($arrayas$clave=>$valor) {
// $array[3] se actualizará con cada valor de $array...
echo"{$clave}=>{$valor}";
print_r($array);
}
// ...hasta que finalmente el penúltimo valor se copia al último valor

// salida:
// 0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
// 1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
// 2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
// 3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
?>

Antes de PHP 5.5.0, referenciar$valorsólo es posible si el array iterado puede ser referenciado (es decir, si es una variable). El siguiente código solamente funciona a partir de PHP 5.5.0:

<?php
foreach (array(1,2,3,4) as &$valor) {
$valor=$valor*2;
}
?>

Nota:

foreachno soporta la capacidad de suprimir mensajes de error usando '@'.

Algunos ejemplos más para demostrar su uso:

<?php
/* Ejemplo 1 de foreach: sólo el valor */

$a= array(1,2,3,17);

foreach (
$aas$v) {
echo
"Valor actual de \$a:$v.\n";
}

/* Ejemplo 2 de foreach: valor (con su notación de acceso manual impreso con fines ilustrativos) */

$a= array(1,2,3,17);

$i=0;/* sólo para efectos ilustrativos */

foreach ($aas$v) {
echo
"\$a[$i] =>$v.\n";
$i++;
}

/* Ejemplo 3 de foreach: clave y valor */

$a= array(
"uno"=>1,
"dos"=>2,
"tres"=>3,
"diecisiete"=>17
);

foreach (
$aas$k=>$v) {
echo
"\$a[$k] =>$v.\n";
}

/* Ejemplo 4 de foreach: arrays multidimensionales */
$a= array();
$a[0][0] ="a";
$a[0][1] ="b";
$a[1][0] ="y";
$a[1][1] ="z";

foreach (
$aas$v1) {
foreach (
$v1as$v2) {
echo
"$v2\n";
}
}

/* Ejemplo 5 de foreach: arrays dinámicos */

foreach (array(1,2,3,4,5) as$v) {
echo
"$v\n";
}
?>

Utilizando arrays anidados con list()

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

PHP 5.5 añade la posibilidad de recorrer un array de arrays y utilizar el array interior en las variables del bucle proporcionandolist()como el valor.

Por ejemplo:

<?php
$array
= [
[
1,2],
[
3,4],
];

foreach (
$arrayas list($a,$b)) {
// $a contiene el primer elemento del array interior,
// y $b contiene el segundo elemento.
echo"A:$a; B:$b\n";
}
?>

El resultado del ejemplo sería:

A: 1; B: 2
A: 3; B: 4

Puedes proporcionar menos elementos alist()de los que hay en el array interior, en cuyo caso los elementos sobrantes del array serán descartados:

<?php
$array
= [
[
1,2],
[
3,4],
];

foreach (
$arrayas list($a)) {
// Observa que no hay $b en este caso.
echo"$a\n";
}
?>

El resultado del ejemplo sería:

1
3

Se generará un notice si no hay suficientes elementos en el array para completar ellist():

<?php
$array
= [
[
1,2],
[
3,4],
];

foreach (
$arrayas list($a,$b,$c)) {
echo
"A:$a; B:$b; C:$c\n";
}
?>

El resultado del ejemplo sería:


Notice: Undefined offset: 2 in example.php on line 7
A: 1; B: 2; C: 

Notice: Undefined offset: 2 in example.php on line 7
A: 3; B: 4; C: 

Historial de cambios

VersiónDescripción
7.0.0foreachya no utiliza el puntero interno al array.
5.5.0Hacer referencia a$valorestá admitido para expresiones. Anteriormente, solamente estaban admitidas las variables.
5.5.0El desempaquetamiento de arrays anidados conlist()está admitido.



break

(PHP 4, PHP 5, PHP 7, PHP 8)

breakfinaliza la ejecución de la estructurafor,foreach,while,do-whileoswitchen curso.

breakacepta un argumento numérico opcional que indica de cuántas estructuras anidadas circundantes se debe salir. El valor predeterminado es1, es decir, solamente se sale de la estructura circundante inmediata.

<?php
$arr
= array('uno','dos','tres','cuatro','pare','cinco');
while (list(,
$val) =each($arr)) {
if (
$val=='pare') {
break;
/* Se puede también escribir 'break 1;' aquí. */
}
echo
"$val<br />\n";
}

/* Utilizar el argumento opcional. */

$i=0;
while (++
$i) {
switch (
$i) {
case
5:
echo
"En 5<br />\n";
break
1;/* Sólo sale del switch. */
case10:
echo
"En 10; saliendo<br />\n";
break
2;/* Sale del switch y del while. */
default:
break;
}
}
?>

Registro de cambios parabreak
VersiónDescripción
5.4.0break 0;ya no es válido. En versiones anteriores se interpretaba igual quebreak 1;.
5.4.0Eliminada la posibilidad de pasar variables (por ejemplo,$num = 2; break $num;) como argumento numérico.



continue

(PHP 4, PHP 5, PHP 7, PHP 8)

continuese utiliza dentro de las estructuras iterativas para saltar el resto de la iteración actual del bucle y continuar la ejecución en la evaluación de la condición, para luego comenzar la siguiente iteración.

Nota:En PHP, la sentenciaswitchse considera una estructura iterativa para los propósitos decontinue.continuese comporta igual quebreak(cuando no se proporcionan argumentos). Si unswitchestá dentro de un bucle,continue 2continurá con la siguiente iteración del bucle externo.

continueacepta un argumento numérico opcional, que indica a cuántos niveles de bucles encerrados se ha de saltar al final. El valor por omisión es1, por lo que salta al final del bucle actual.

<?php
while (list($clave,$valor) =each($arr)) {
if (!(
$clave%2)) {// saltar los miembros pares
continue;
}
hacer_algo($valor);
}

$i=0;
while (
$i++ <5) {
echo
"Exterior<br />\n";
while (
1) {
echo
"Medio<br />\n";
while (
1) {
echo
"Interior<br />\n";
continue
3;
}
echo
"Esto nunca se imprimirá.<br />\n";
}
echo
"Ni esto tampoco.<br />\n";
}
?>

Omitir el punto y coma después delcontinuepuede llevar a confusión. He aquí un ejemplo de lo que no se debe hacer.

<?php
for ($i=0;$i<5; ++$i) {
if (
$i==2)
continue
print
"$i\n";
}
?>

Se esperaría que el resultado fuera:

0
1
3
4

pero, en versiones de PHP anteriores a la 5.4.0, la salida de este script será:

2

debido a quecontinue print "$i\n";se evalúa completo como una sola expresión, y asíprintse llama solamente cuando$i == 2es verdadero. (El valor de retorno deprintes pasado acontinuecomo el argumento numérico.)

Nota:

A partir de PHP 5.4.0, el ejemplo anterior emitirá un errorE_COMPILE_ERROR.

Registro de cambios paracontinue
VersiónDescripción
5.4.0continue 0;ya no es válido. En versiones anteriores era interpretado de la misma manera quecontinue 1;.
5.4.0Se eliminó la posibilidad de pasar variables (por ejemplo,$num = 2; continue $num;) como el argumento numérico.



switch

(PHP 4, PHP 5, PHP 7, PHP 8)

La sentenciaswitches similar a una serie de sentencias IF en la misma expresión. En muchas ocasiones, es posible que se quiera comparar la misma variable (o expresión) con muchos valores diferentes, y ejecutar una parte de código distinta dependiendo de a que valor es igual. Para esto es exactamente la expresiónswitch.

Nota:Cabe señalar que a diferencia de algunos otros lenguajes, la sentenciacontinuese aplica aswitchy actúa de manera similar abreak. Si se tiene unswitchdentro de un bucle y se desea continuar a la siguiente iteración de del ciclo exterior, se utilizacontinue 2.

Nota:

Tener en cuenta que switch/case hacecomparaciones flexibles.

Historial de cambios
VersiónDescripción
7.0.0Múltiples casos predeterminados (default) emitirán un error de tipoE_COMPILE_ERROR.

Los dos ejemplos siguientes son dos formas diferentes de escribir lo mismo, uno con una serie de sentenciasifyelseif, y el otro usando la sentenciaswitch:

Ejemplo #1 Estructuraswitch

<?php
if ($i==0) {
echo
"i es igual a 0";
} elseif (
$i==1) {
echo
"i es igual a 1";
} elseif (
$i==2) {
echo
"i es igual a 2";
}

switch (
$i) {
case
0:
echo
"i es igual a 0";
break;
case
1:
echo
"i es igual a 1";
break;
case
2:
echo
"i es igual a 2";
break;
}
?>

Ejemplo #2 Estruturaswitchpermite el uso de strings

<?php
switch ($i) {
case
"manzana":
echo
"i es una manzana";
break;
case
"barra":
echo
"i es una barra";
break;
case
"pastel":
echo
"i es un pastel";
break;
}
?>

Es importante entender cómo la sentenciaswitches ejecutada con el fin de evitar errores. La sentenciaswitchejecuta línea por línea (en realidad, sentencia por sentencia). Al principio, ningún código es ejecutado. Solo cuando se encuentra una sentenciacasecuya expresión se evalúa a un valor que coincida con el valor de la con un valor que coincide con el valor de la expresiónswitch, PHP comienza a ejecutar la sentencias. PHP continúa ejecutando las sentencias hasta el final del bloqueswitch, o hasta la primera vez que vea una sentenciabreak. Si no se escribe una sentenciabreakal final de la lista de sentencias de un caso, PHP seguirá ejecutando las sentencias del caso siguiente. Por ejemplo:

<?php
switch ($i) {
case
0:
echo
"i es igual a 0";
case
1:
echo
"i es igual a 1";
case
2:
echo
"i es igual a 2";
}
?>

Aquí, si$ies igual a 0, PHP ejecutaría todas las sentencias echo! Si$ies igual a 1, PHP ejecutaría las últimas dos sentencias echo. Se obtendría el comportamiento esperado (se mostraría 'i es igual a 2') sólo si$ies igual a 2. Por lo tanto, es importante no olvidar las sentenciasbreak(aunque es posible que se desee evitar proporcionarlas a propósito bajo determinadas circunstancias).

En una sentenciaswitch, la condición es evaluada sólo una vez y el resultado es comparado con cada una de las sentenciascase. En una sentenciaelseif, la condición es evaluada otra vez. Si la condición es más complicada que una simple comparación y/o está en un bucle estrecho, unswitchpuede ser más rápido.

La lista de sentencias para un caso también puede estar vacía, lo cual simplemente pasa el control a la lista de sentencias para el siguiente caso.

<?php
switch ($i) {
case
0:
case
1:
case
2:
echo
"i es menor que 3 pero no negativo";
break;
case
3:
echo
"i es 3";
}
?>

Un caso especial es eldefault. Este caso coincide con cualquier cosa que no se haya correspondido por los otros casos. Por ejemplo:

<?php
switch ($i) {
case
0:
echo
"i es igual a 0";
break;
case
1:
echo
"i es igual a 1";
break;
case
2:
echo
"i es igual a 2";
break;
default:
echo
"i no es igual a 0, 1 ni 2";
}
?>

La sintaxis alternativa para las estructuras de control es compatible con los switch. Para obtener más información, consulteSintaxis alternativa de estructuras de control.

<?php
switch ($i):
case
0:
echo
"i es igual a 0";
break;
case
1:
echo
"i es igual a 1";
break;
case
2:
echo
"i es igual a 2";
break;
default:
echo
"i no es igual a 0, 1 ni 2";
endswitch;
?>

Es posible utilizar un punto y coma en lugar de dos puntos después de un caso como:

<?php
switch($beer)
{
case
'tuborg';
case
'carlsberg';
case
'heineken';
echo
'Buena elección';
break;
default;
echo
'Por favor haga una nueva selección...';
break;
}
?>



match

(PHP 8)

La expresiónmatchramifica la evaluación basada en una comprobación de identidad de un valor. De forma similar a una sentenciaswitch, una expresiónmatchtiene una expresión de sujeto que se compara con múltiples alternativas. A diferencia deswitch, se evaluará a un valor muy parecido al de las expresiones ternarias. A diferencia deswitch, la comparación es una comprobación de identidad (===) en lugar de una comprobación de igualdad débil (==). Las expresiones match están disponibles a partir de PHP 8.0.0.

Ejemplo #1 Estructura de una expresiónmatch

<?php
$return_value
=match(subject_expression) {
single_conditional_expression=>return_expression,
conditional_expression1,conditional_expression2=>return_expression,
};
?>

Nota:El resultado de una expresiónmatchno necesita ser utilizado.

Nota:Una expresiónmatchdebeterminar con un punto y coma;.

La expresiónmatches similar a una sentenciaswitchpero tiene algunas diferencias clave:

  • Un brazo dematchcompara los valores estrictamente (===) en lugar de hacerlo de forma suelta como lo hace la sentencia switch.
  • Una expresiónmatchretorna un valor.
  • Los brazos deMatchno pasan a casos posteriores como lo hacen las sentenciasswitch.
  • Una expresiónmatchdebe ser completa.

Como las expresionesswitch, las expresionesmatchse ejecutan de brazo a brazo. Al principio, no se ejecuta ningún código. Las expresiones condicionales sólo se evalúan si todas las anteriores no coinciden con la expresión del sujeto. Sólo se evaluará la expresión de retorno correspondiente a la expresión condicional que coincida. Por ejemplo:

<?php
$result
=match($x) {
foo() => ...,
$this->bar() => ...,// bar() no se llama si foo() === $x
$this->baz=>beep(),// beep() no se llama a menos que $x === $this->baz
// etc.
};
?>

Los brazos de la expresiónmatchpueden contener varias expresiones separadas por una coma. Se trata de un OR lógico, y es una abreviatura de múltiples brazos match con el mismo lado derecho.

<?php
$result
=match($x) {
// Este brazo match:
$a,$b,$c=>5,
// Es equivalente a estos tres:
$a=>5,
$b=>5,
$c=>5,
};
?>

Un caso especial es el patróndefault. Este patrón permite hacer coincidir cualquier cosa que no se haya hecho coincidir previamente. Por ejemplo:

<?php
$expressionResult
=match($condition) {
1,2=>foo(),
3,4=>bar(),
default =>
baz(),
};
?>

Nota:Múltiples patrones default lanzarán un errorE_FATAL_ERROR.

Una expresiónmatchdebe ser completa. Si la expresión del sujeto no es manejada por ningún brazo match se lanza unUnhandledMatchError.

Ejemplo #2 Ejemplo de una expresión match no controlada

<?php
$condition
=5;

try {
match($condition) {
1,2=>foo(),
3,4=>bar(),
};
} catch (\
UnhandledMatchError $e) {
var_dump($e);
}
?>

El resultado del ejemplo sería:

object(UnhandledMatchError)#1 (7) {
  ["message":protected]=>
  string(33) "Unhandled match value of type int"
  ["string":"Error":private]=>
  string(0) ""
  ["code":protected]=>
  int(0)
  ["file":protected]=>
  string(9) "/in/ICgGK"
  ["line":protected]=>
  int(6)
  ["trace":"Error":private]=>
  array(0) {
  }
  ["previous":"Error":private]=>
  NULL
}

Usando expresiones match para manejar comprobaciones de no identidad

Es posible utilizar un expresiónmatchpara manejar casos de condicionales de no identidad usandotruecomo expresión del sujeto.

Ejemplo #3 Uso de expresiones match generalizadas para ramificar en rangos de integers

<?php

$age
=23;

$result=match(true) {
$age>=65=>'senior',
$age>=25=>'adult',
$age>=18=>'young adult',
default =>
'kid',
};

var_dump($result);
?>

El resultado del ejemplo sería:

string(11) "young adult"

Ejemplo #4 Uso de expresiones match generalizadas para ramificar el contenido de strings.

<?php

$text
='Bienvenue chez nous';

$result=match(true) {
str_contains($text,'Welcome') ||str_contains($text,'Hello') =>'en',
str_contains($text,'Bienvenue') ||str_contains($text,'Bonjour') =>'fr',
// ...
};

var_dump($result);
?>

El resultado del ejemplo sería:

string(2) "fr"


declare

(PHP 4, PHP 5, PHP 7, PHP 8)

El constructordeclarees usado para fijar directivas de ejecución para un bloque de código. La sintaxis dedeclarees similar a la sintaxis de otros constructores de control de flujo:

declare (directive)
    statement

La seccióndirectivepermite que el comportamiento dedeclaresea configurado. Actualmente, solamente están reconocidas tres directivas:ticks(véase abajo para más información sobre la directivaticks),encoding(véase abajo para más información sobre la directivaencoding) ystrict_types(para más infomación, véase la secciónstrictde la página de Argumentos de funciones)

VersiónDescripción
7.0.0Se añadió la directivastrict_types
5.3.0Se añadió la directivaencoding

Ya que las directivas se manejan mientras el fichero está siendo compilado, solamente se pueden proporcionar literales como valores de directivas. No se pueden emplear variables ni constantes. Como ejemplo:

<?php
// Esto es válido:
declare(ticks=1);

// Esto no es válido:
constTICK_VALUE=1;
declare(
ticks=TICK_VALUE);
?>

La partestatementdel bloquedeclareserá ejecutada - como se ejecuta y que efectos secundarios ocurran durante la ejecución puede depender de la directiva fijada en el bloquedirective.

El constructordeclaretambién se puede utilizar en el alcance global, afectando a todo el código que le sigue (sin embargo, si el archivo con eldeclarefue incluido entonces no afectará al archivo padre).

<?php
// estos son lo mismo:

// se puede usar ésto:
declare(ticks=1) {
// script entero aquí
}

// o se puede usar ésto:
declare(ticks=1);
// script entero aquí
?>

Ticks

Un tick es un evento que ocurre para cada sentencia tickableNde bajo nivel ejecutada por el intérprete dentro del bloquedeclare. El valor paraNse especifica usandoticks=Ndentro del bloque dedeclarede la seccióndirective.

No todas las sentencias son tickable. Por lo general, expresiones de condición y expresiones de argumento no son tickables.

Los eventos que ocurren en cada tick se especifican mediante laregister_tick_function(). Ver el ejemplo abajo para más detalles. Tener en cuenta que más de un evento puede ocurrir por cada tick.

Ejemplo #1 Ejemplo de uso del tick

<?php

declare(ticks=1);

// Una función llamada en cada evento tick
functiontick_handler()
{
echo
"tick_handler() llamado\n";
}

register_tick_function('tick_handler');

$a=1;

if (
$a>0) {
$a+=2;
print(
$a);
}

?>

Ejemplo #2 Ejemplo de uso de ticks

<?php

functiontick_handler()
{
echo
"tick_handler() llamado\n";
}

$a=1;
tick_handler();

if (
$a>0) {
$a+=2;
tick_handler();
print(
$a);
tick_handler();
}
tick_handler();

?>

Véase tambiénregister_tick_function()yunregister_tick_function().

Encoding

Una codificación de script puede ser especificada para cada script usando la directivaencoding.

Ejemplo #3 Declarando un encoding para el script

<?php
declare(encoding='ISO-8859-1');
// código aquí
?>

Precaución

Cuando se combina con espacios de nombres, la única sintaxis legal para declarar esdeclare(encoding='...');donde...es el valor del encoding.declare(encoding='...') {}resultará en un error de análisis cuando se combina con espacios de nombres.

El valor declarado de encoding es ignorado en PHP 5.3 a menos que php esté compilado con--enable-zend-multibyte.

Tener en cuenta que PHP no expone si--enable-zend-multibytefue utilizado para compilar PHP que no sea porphpinfo().

Ver tambiénzend.script_encoding.



return

(PHP 4, PHP 5, PHP 7, PHP 8)

returndevuelve el control del programa al módulo que lo invoca. La ejecución vuelve a la siguiente expresión después del módulo que lo invoca.

Si se llama desde una función, la sentenciareturninmediatamente termina la ejecución de la función actual, y devuelve su argumento como el valor de la llamada a la función.returntambién termina la ejecución de una sentenciaeval()o un archivo de script.

Si se llama desde el ámbito global, entonces la ejecución del script actual se termina. Si el archivo script actual fue incluido o requerido conincludeorequire, entonces el control es pasado de regreso al archivo que hizo el llamado. Además, si el archivo script actual fue incluido coninclude, entonces el valor dado areturnserá retornado como el valor de la llamadainclude. Sireturnes llamado desde dentro del fichero del script principal, entonces termina la ejecución del script. Si el archivo script actual fue nombrado por las opciones de configuraciónauto_prepend_fileoauto_append_fileenphp.ini, entonces se termina la ejecución de ese archivo script.

Para más información, verRetornando valores.

Nota:Cabe señalar que dado quereturnes un constructor del lenguaje y no una función, los paréntesis que rodean su argumento no son obligatorios y se desaconseja su uso.

Nota:Si no se suministra un parámetro, entonces el paréntesis debe omitirse ynullserá retornado. Llamadas areturncon paréntesis pero sin argumentos resultarán en un error del intérprete.



require

(PHP 4, PHP 5, PHP 7, PHP 8)

requirees idéntico aincludeexcepto que en caso de fallo producirá un error fatal de nivelE_COMPILE_ERROR. En otras palabras, éste detiene el script mientras queincludesólo emitirá una advertencia (E_WARNING) lo cual permite continuar el script.

Véase la documentación deincludepara más información.



include

(PHP 4, PHP 5, PHP 7, PHP 8)

La sentenciaincludeincluye y evalúa el archivo especificado.

La siguiente documentación también se aplica arequire.

Los archivos son incluidos con base en la ruta de acceso dada o, si ninguna es dada, elinclude_pathespecificado. Si el archivo no se encuentra en elinclude_path,includefinalmente verificará en el propio directorio del script que hace el llamado y en el directorio de trabajo actual, antes de fallar. El constructorincludeemitirá unaadvertenciasi no puede encontrar un archivo, éste es un comportamiento diferente al derequire, el cual emitirá unerror fatal..

Si una ruta es definida — ya sea absoluta (comenzando con una letra de unidad o\en Windows o/en sistemas Unix/Linux) o relativa al directorio actual (comenzando con.o..) — elinclude_pathserá ignorado por completo. Por ejemplo, si un nombre de archivo comienza con../, el interprete buscará en el directorio padre para encontrar el archivo solicitado.

Para más información sobre como PHP maneja la inclusión de archivos y la ruta de accesos para incluir, ver la documentación deinclude_path.

Cuando se incluye un archivo, el código que contiene hereda elámbito de las variablesde la línea en la cual ocurre la inclusión. Cualquier variable disponible en esa línea del archivo que hace el llamado, estará disponible en el archivo llamado, desde ese punto en adelante. Sin embargo, todas las funciones y clases definidas en el archivo incluido tienen el ámbito global.

Ejemplo #1 Ejemplo básico deinclude

vars.php
<?php

$color
='verde';
$fruta='manzana';

?>

test.php
<?php

echo"Una$fruta$color";// Una

include'vars.php';

echo
"Una$fruta$color";// Una manzana verde

?>

Si la inclusión ocurre al interior de una función dentro del archivo que hace el llamado, entonces todo el código contenido en el archivo llamado se comportará como si hubiera sido definida dentro de esa función. Por lo tanto, seguirá el ámbito de las variables de esa función. Una excepción a esta regla son lasconstantes mágicaslas cuales son evaluadas por el intérprete antes que ocurra la inclusión.

Ejemplo #2 Incluyendo dentro de funciones

<?php

functionfoo()
{
global
$color;

include
'vars.php';

echo
"Una$fruta$color";
}

/* vars.php está en el ámbito de foo() así que *
* $fruta NO está disponible por fuera de éste *
* ámbito. $color sí está porque fue declarado *
* como global. */

foo();// Una manzana verde
echo"Una$fruta$color";// Una verde

?>

Cuando un archivo es incluido, el intérprete abandona el modo PHP e ingresa al modo HTML al comienzo del archivo objetivo y se reanuda de nuevo al final. Por esta razón, cualquier código al interior del archivo objetivo que deba ser ejecutado como código PHP, tendrá que ser encerrado dentro deetiquetas válidas de comienzo y terminación de PHP.

Si las "envolturas URL include" están activadas en PHP, se puede especificar el archivo a ser incluido usando una URL (vía HTTP u otra envoltura soportada - verProtocolos y Envolturas soportadospara una lista de protocolos) en lugar de una ruta de acceso local. Si el servidor objetivo interpreta el archivo objetivo como código PHP, las variables se pueden pasar al archivo incluido usando una string de petición como la usada con HTTP GET. Esto no es, en estricto rigor, lo mismo que haber incluido el archivo y que haya heredado el ámbito de variables del archivo padre; el script realmente está siendo ejecutado en el servidor remoto y el resultado entonces se incluye dentro del script local.

Ejemplo #3includepor medio de HTTP

<?php

/* Este ejemplo asume que www.example.com está configurado para interpretar archivos
* .php y no archivos .txt. Además, aquí 'Funciona' quiere decir que las variables
* $foo y $bar están disponibles dentro del archivo incluido. */

// No funciona; file.txt no puede ser manejado por www.example.com como PHP
include'http://www.example.com/file.txt?foo=1&bar=2';

// No funciona; busca por un archivo llamado 'file.php?foo=1&bar=2' en el
// sistema de archivos local.
include'file.php?foo=1&bar=2';

// Si funciona.
include'http://www.example.com/file.php?foo=1&bar=2';

$foo=1;
$bar=2;
include
'file.txt';// Funciona.
include'file.php';// Funciona.

?>

Advertencia

Advertencia de seguridad

El archivo remoto puede ser procesado en el servidor remoto (dependiendo de la extensión del archivo y del hecho de si el servidor remoto corre PHP o no) pero aun así tiene que producir un script PHP válido, porque será procesado en el servidor local. Si el archivo desde el servidor remoto debe ser procesado allá y entregar la salida solamente,readfile()es la mejor función para usar. De lo contrario, debe tenerse especial cuidado para asegurar que el script remoto produce un código válido y deseado.

Ver tambiénArchivos remotos,fopen()yfile()para información relacionada.

Manejando retornos:includedevuelveFALSEen caso de falla y eleva una advertencia. Inclusiones exitosas, a menos que sea reemplazado por el archivo incluido, devolverá1. Es posible ejecutar una sentenciareturndentro de un archivo incluido con el fin de terminar el procesamiento en ese archivo y volver al script que lo llamó. Además, es posible retornar valores desde los archivos incluidos. Se puede tomar el valor de la llamada "include" de la misma forma como se haría con una función normal. Esto no es, sin embargo, posible si se incluyen archivos remotos, a menos que la salida del archivo remoto tenga unasetiquetas válidas de inicio y terminación de PHP(igual que con cualquier archivo local). Se pueden declarar las variables necesarias dentro de esas etiquetas y serán introducidas en cualquiera sea el punto del archivo en el cual fue incluido.

Debido a queincludees un constructor especial del lenguaje, los paréntesis no son necesarios en torno a su argumento. Se debe tener cuidado cuando se compara el valor de retorno.

Ejemplo #4 Comparando el valor de retorno de include

<?php
// no funcionará, se evalúa como include(('vars.php') == TRUE), es decir, include('')
if (include('vars.php') ==TRUE) {
echo
'OK';
}

// sí funciona
if ((include'vars.php') ==TRUE) {
echo
'OK';
}
?>

Ejemplo #5includey la sentenciareturn

return.php
<?php

$var
='PHP';

return
$var;

?>

noreturn.php
<?php

$var
='PHP';

?>

testreturns.php
<?php

$foo
= include'return.php';

echo
$foo;// muestra 'PHP'

$bar= include'noreturn.php';

echo
$bar;// muestra 1

?>

$bartiene el valor1debido a que el include fue exitoso. Nótese la diferencia entre los ejemplos anteriores. El primero usareturndentro del archivo incluido, mientras que el otro no. Si el archivo no se pueden incluir, se retornafalsey se emite unE_WARNING.

Si hay funciones definidas en el archivo incluido, se pueden utilizar en el archivo principal independientemente que hayanreturnantes o después. Si el archivo se incluye dos veces, PHP 5 arrojará un error fatal ya que las funciones ya han sido declaradas, mientras que PHP 4 no se queja acerca de las funciones definidas después de unreturn. Se recomienda el uso deinclude_onceen lugar de comprobar si el archivo ya estaba incluido y hacer el retorno de forma condicionada dentro del archivo incluido.

Otra forma de "incluir" un archivo PHP en una variable es capturar la salida mediante el uso deFunciones de control de salidaconinclude. Por ejemplo:

Ejemplo #6 Usando buffering de salida para incluir un archivo PHP dentro de una cadena

<?php
$string
=get_include_contents('somefile.php');

function
get_include_contents($filename) {
if (
is_file($filename)) {
ob_start();
include
$filename;
return
ob_get_clean();
}
return
false;
}

?>

Con el fin de incluir archivos de forma automática dentro de scripts, véase también las opciones de configuraciónauto_prepend_fileandauto_append_fileenphp.ini.

Nota:Puesto que esto es una construcción del lenguaje y no una función, no puede ser llamada usandofunciones variables.

Ver tambiénrequire,require_once,include_once,get_included_files(),readfile(),virtual()yinclude_path.



require_once

(PHP 4, PHP 5, PHP 7, PHP 8)

La sentenciarequire_oncees idéntica arequireexcepto que PHP verificará si el archivo ya ha sido incluido y si es así, no se incluye (require) de nuevo.

Ver la documentación deinclude_oncepara información sobre el comportamiento de_once, y como difiere de sus hermanos no_once.



include_once

(PHP 4, PHP 5, PHP 7, PHP 8)

La sentenciainclude_onceincluye y evalúa el fichero especificado durante la ejecución del script. Tiene un comportamiento similar al de la sentenciainclude, siendo la única diferencia de que si el código del fichero ya ha sido incluido, no se volverá a incluir, e include_once devolverátrue. Como su nombre indica, el fichero será incluido solamente una vez.

include_oncese puede utilizar en casos donde el mismo fichero podría ser incluido y evaluado más de una vez durante una ejecución particular de un script, así que en este caso, puede ser de ayuda para evitar problemas como la redefinición de funciones, reasignación de valores de variables, etc.

Véase la documentación deincludepara más información sobre cómo funciona esta función.



goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

¿Qué es lo peor que podría suceder si utiliza goto?
Imagen cortesía de» xkcd

El operadorgotopuede ser usado para saltar a otra sección en el programa. El punto de destino es especificado mediante una etiqueta seguida de dos puntos y la instrucción es dada comogotoseguida de la etiqueta del destino deseado. Estegotono es completamente sin restricciones. La etiqueta de destino debe estar dentro del mismo fichero y contexto, lo que significa que no se puede saltar fuera de una función o método, ni se puede saltar dentro de uno. Tampoco se puede saltar dentro de cualquier clase de estructura de bucle o switch. Se puede saltar fuera de estos y un uso común es utilizar ungotoen lugar de unbreakmulti-nivel.

Ejemplo #1 Ejemplo degoto

<?php
gotoa;
echo
'Foo';

a:
echo
'Bar';
?>

El resultado del ejemplo sería:

Bar

Ejemplo #2 Ejemplo degotoen un bucle

<?php
for($i=0,$j=50;$i<100;$i++) {
while(
$j--) {
if(
$j==17) gotoend;
}
}
echo
"i =$i";
end:
echo
'j alcanzó 17';
?>

El resultado del ejemplo sería:

j alcanzó 17

Ejemplo #3 Esto no funcionará

<?php
gotoloop;
for(
$i=0,$j=50;$i<100;$i++) {
while(
$j--) {
loop:
}
}
echo
"$i=$i";
?>

El resultado del ejemplo sería:

Fatal error: 'goto' into loop or switch statement is disallowed in script on line 2
(Error fatal: 'goto' hacia el interior de un bucle o sentencia switch no esta permitido en el script en la línea 2)

Nota:

El operadorgotoestá disponible a partir de PHP 5.3.




Funciones

Tabla de contenidos


Funciones definidas por el usuario

Una función puede ser definida empleando una sintaxis como la siguiente:

Ejemplo #1 Seudocódigo para demostrar el uso de funciones

<?php
functionfoo($arg_1,$arg_2,/* ..., */$arg_n)
{
echo
"Función de ejemplo.\n";
return
$valor_devuelto;
}
?>

Cualquier código PHP válido puede aparecer dentro de una función, incluso otras funciones y definiciones declases.

Los nombres de las funciones siguen las mismas reglas que las demás etiquetas de PHP. Un nombre de función válido comienza con una letra o guión bajo, seguido de cualquier número de letras, números o guiones bajos. Como expresión regular se expresaría así:^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$.

No es necesario definir una función antes de que sea referenciada,exceptocuando esta esté condicionalmente definida como se muestra en los dos ejemplos de abajo.

Cuando una función está definida de una forma condicional como en los dos ejemplos siguientes, sus definiciones deben ser procesadasantesde ser llamadas.

Ejemplo #2 Funciones condicionales

<?php

$hacer_algo
=true;

/* No podemos llamar a foo() desde aquí
ya que no existe aún,
pero podemos llamar a bar() */

bar();

if (
$hacer_algo) {
function
foo()
{
echo
"No existo hasta que la ejecución del programa llegue hasta mí.\n";
}
}

/* Ahora podemos llamar de forma segura a foo()
ya que $hacer_algo se evaluó como verdadero */

if ($hacer_algo)foo();

function
bar()
{
echo
"Existo desde el momento inmediato que comenzó el programa.\n";
}

?>

Ejemplo #3 Funciones dentro de funciones

<?php
functionfoo()
{
function
bar()
{
echo
"No existo hasta que se llame a foo().\n";
}
}

/* No podemos llamar aún a bar()
ya que no existe. */

foo();

/* Ahora podemos llamar a bar(),
el procesamiento de foo()
la ha hecho accesible. */

bar();

?>

Todas las funciones y clases de PHP tienen ámbito global. Se pueden llamar desde fuera de una función incluso si fueron definidas dentro, y viceversa.

PHP no admite la sobrecarga de funciones, ni es posible 'desdefinir' ni redefinir funciones previamente declaradas.

Nota:Los nombres de las fuciones son insensibles a mayúsculas-minúsculas, aunque es una buena idea llamar a las funciones tal y como aparecen en sus declaraciones.

Las funciones admiten unnúmero variable de argumentosyargumentos predeterminados. Véanse también las referencias de funciones parafunc_num_args(),func_get_arg(), yfunc_get_args()para más información.

En PHP es posible llamar a funciones recursivas.

Ejemplo #4 Funciones recursivas

<?php
functionrecursividad($a)
{
if (
$a<20) {
echo
"$a\n";
recursividad($a+1);
}
}
?>

Nota:Las llamadas a funciones/métodos recursivos con más de 100-200 niveles de recursividad pueden agotar la pila y ocasionar la finalización del script en curso. Especialmente, las recurisvidades infinitas están consideradas un error de programación.



Argumentos de funciones

Cualquier información puede ser pasada a las funciones mediante la lista de argumentos, la cual es una lista de expresiones delimitadas por comas. Los argumentos son evaluados de izquierda a derecha.

PHP admite el paso de argumentos por valor (lo predeterminado),el paso por referencia, yvalores de argumentos predeterminados. LasListas de argumentos de longitud variabletambién están soportadas.

Ejemplo #1 Pasar arrays a funciones

<?php
functiontomar_array($entrada)
{
echo
"$entrada[0]+$entrada[1]= ".$entrada[0]+$entrada[1];
}
?>

Paso de argumentos por referencia

Por defecto, los argumentos de las funciones son pasados por valor (así, si el valor del argumento dentro de la función cambia, este no cambia fuera de la función). Para permitir a una función modificar sus argumentos, éstos deben pasarse por referencia.

Para hacer que un argumento a una función sea siempre pasado por referencia hay que anteponer al nombre del argumento el signo 'et' (&) en la definición de la función:

Ejemplo #2 Paso de parámetros de una función por referencia

<?php
functionañadir_algo(&$cadena)
{
$cadena.='y algo más.';
}
$cad='Esto es una cadena, ';
añadir_algo($cad);
echo
$cad;// imprime 'Esto es una cadena, y algo más.'
?>

Valores de argumentos predeterminados

Una función puede definir valores predeterminados al estilo de C++ para argumentos escalares como sigue:

Ejemplo #3 Uso de parámetros predeterminados en funciones

<?php
functionhacer_café($tipo="capuchino")
{
return
"Hacer una taza de$tipo.\n";
}
echo
hacer_café();
echo
hacer_café(null);
echo
hacer_café("espresso");
?>

El resultado del ejemplo sería:

Hacer una taza de capuchino.
Hacer una taza de .
Hacer una taza de espresso.

PHP también permite el uso dearrays y del tipo especialnullcomo valores predeterminados, por ejemplo:

Ejemplo #4 Usar tipos no escalares como valores predeterminados

<?php
functionhacer_café($tipos= array("capuchino"),$fabricanteCafé=NULL)
{
$aparato=is_null($fabricanteCafé) ?"las manos":$fabricanteCafé;
return
"Hacer una taza de ".join(", ",$tipos)." con$aparato.\n";
}
echo
hacer_café();
echo
hacer_café(array("capuchino","lavazza"),"una tetera");
?>

El valor predeterminado debe ser una expresión constante, no (por ejemplo) una variable, un miembro de una clase o una llamada a una función.

Obsérvese que cuando se emplean argumentos predeterminados, cualquiera de ellos debería estar a la derecha de los argumentos no predeterminados; si no, las cosas no funcionarán como se esperaba. Considérese el siguiente trozo de código:

Ejemplo #5 Uso incorrecto de argumentos predeterminados en una función

<?php
functionhacer_yogur($tipo="acidófilo",$sabor)
{
return
"Hacer un tazón de yogur$tipode$sabor.\n";
}

echo
hacer_yogur("frambuesa");// no funcionará como se esperaba
?>

El resultado del ejemplo sería:

Warning: Missing argument 2 in call to hacer_yogur() in
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Hacer un tazón de yogur frambuesa de .

Ahora, compare el ejemplo de arriba con este:

Ejemplo #6 Uso correcto de argumentos predeterminados en una función

<?php
functionhacer_yogur($sabor,$tipo="acidófilo")
{
return
"Hacer un tazón de yogur$tipode$sabor.\n";
}

echo
hacer_yogur("frambuesa");// funciona como se esperaba
?>

El resultado del ejemplo sería:

Hacer un tazón de yogur acidófilo de frambuensa.

Nota:A partir de PHP 5, los argumentos pasados por referencia pueden tener un valor predeterminado.

Declaraciones de tipo

Nota:

La declaración de tipos también se conoce como 'Determinación de tipos' en PHP 5.

Las declaraciones de tipo permiten a las funciones requerir que los parámetros sean de cierto tipo durante una llamada. Si el valor dado es de un tipo incorrecto, se generará un error: en PHP 5, este error es un error fatal recuperable, mientras que PHP 7 lanzará una excepciónTypeError.

Para especificar una declaración de tipo, debe anteponerse el nombre del tipo al nombre del parámetro. Se puede hacer que una declaración acepte valoresnullsi el valor predeterminado del parámetro se establece anull.

Tipos válidos

TipoDescripciónVersión de PHP mínima
nombre de clase/interfazEl parámetro debe ser unainstanceofdel nombre de la clase o interfaz dada.PHP 5.0.0
selfEl parámetro debe ser unainstanceofde la misma clase donde está definido el método. Esto solamente se puede utilizar en clases y métodos de instancia.PHP 5.0.0
arrayEl parámetro debe ser unarray.PHP 5.1.0
callableEl parámetro debe ser uncallableválido.PHP 5.4.0
boolEl parámetro debe ser un valor de tipoboolean.PHP 7.0.0
floatEl parámetro debe ser un número de tipofloat.PHP 7.0.0
intEl parámetro debe ser un valor de tipointeger.PHP 7.0.0
stringEl parámetro debe ser unstring.PHP 7.0.0
iterableEl parámetro debe ser unarrayo unainstanceofTraversable.PHP 7.1.0
objectEl parámetro debe ser unobject.PHP 7.2.0
Advertencia

Los alias de los tipos escalares anteriores no están admitidos. En su lugar, son tratados como nombres de clases o de interfaces. Por ejemplo, el empleo debooleancomo parámetro o como tipo devuelto requerirá un argumento o un valor devuelto que sea unaaninstanceofde la clase o interfazboolean, más que el tipobool:

<?php
functionprueba(boolean $param) {}
prueba(true);
?>

El resultado del ejemplo sería:

 Fatal error: Uncaught TypeError: Argument 1 passed to test() must be an instance of boolean, boolean given, called in - on line 1 and defined in -:1
 

Ejemplos

Ejemplo #7 Declaración básica de tipo clase

<?php
classC{}
class
DextendsC{}

// Esta no extiende a C.
classE{}

function
f(C $c) {
echo
get_class($c)."\n";
}

f(newC);
f(newD);
f(newE);
?>

El resultado del ejemplo sería:

C
D

Fatal error: Uncaught TypeError: Argument 1 passed to f() must be an instance of C, instance of E given, called in - on line 14 and defined in -:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
  thrown in - on line 8

Ejemplo #8 Declaración básica de tipo interfaz

<?php
interfaceI{ public functionf(); }
class
CimplementsI{ public functionf() {} }

// Esta no implementa I.
classE{}

function
f(I $i) {
echo
get_class($i)."\n";
}

f(newC);
f(newE);
?>

El resultado del ejemplo sería:

C

Fatal error: Uncaught TypeError: Argument 1 passed to f() must implement interface I, instance of E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
  thrown in - on line 8

Ejemplo #9 Tipos de parámetros pasados por referencia

Los tipos declarados de parámetros de referencia se comprueban en la entrada de la función, pero no cuando la función vuelve, así que después de que la función haya vuelto, el el tipo de argumento puede haber cambiado.

<?php
functionarray_baz(array &$param)
{
$param=1;
}
$var= [];
array_baz($var);
var_dump($var);
array_baz($var);
?>

El resultado del ejemplo sería algo similar a:

int(1)

Fatal error: Uncaught TypeError: Argument 1 passed to array_baz() must be of the type array, int given, called in %s on line %d

Ejemplo #10 Declaración de tipo nulo

<?php
classC{}

function
f(C $c=null) {
var_dump($c);
}

f(newC);
f(null);
?>

El resultado del ejemplo sería:

object(C)#1 (0) {
}
NULL

Tipificación estricta

Por defecto, PHP fuerza a los valores de un tipo erróneo a ser del tipo escalar esperado si es posible. Por ejemplo, una función a la que se le pasa unintegerpara un parámetro que se prevé sea unstringobtendrá una variable de tipostring.

Es posible habilitar el modo estricto en función de cada fichero. El el modo estricto solamente será aceptada una variable del tipo exacto de la declaración de tipo, o será lanzada unaTypeError. La única excepción a esta regla es que se podría proporcionar unintegera una función que espere unfloat. Las llamadas a funciones desde dentro de funciones internas no se verán afectadas por la declaraciónstrict_types.

Para habilitar el modo escricto se emplea la sentenciadeclarecon la declaraciónstrict_types:

Precaución

Habilitar el modo esctricto también afectará a lasdeclaraciones de tipo de devolución.

Nota:

La tipificación estricta se aplica a las llamadas a funciones hechas desdedentrodel fichero con la tipificación estricta habilitada, no a las funciones declaradas dentro del fichero. Si un fichero sin la tipificación estricta habilitada realiza una llamada a una función definida en un fichero con tipificación estricta, será respetada la preferencia del llamador (tipificación débil), y se forzará el valor.

Nota:

La tipificación estricta solamente se define para declaraciones de tipos escalares, y como tal, requiere PHP 7.0.0 o posterior, ya que las declaraciones de tipo escalar fueron añadidas en esta versión.

Ejemplo #11 Tipificación estricta

<?php
declare(strict_types=1);

function
sum(int $a,int $b) {
return
$a+$b;
}

var_dump(sum(1,2));
var_dump(sum(1.5,2.5));
?>

El resultado del ejemplo sería:

int(3)

Fatal error: Uncaught TypeError: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
  thrown in - on line 4

Ejemplo #12 Tipificación débil

<?php
functionsum(int $a,int $b) {
return
$a+$b;
}

var_dump(sum(1,2));

// Estos números serán forzados a ser enteros: ¡observe la salida de abajo!
var_dump(sum(1.5,2.5));
?>

El resultado del ejemplo sería:

int(3)
int(3)

Ejemplo #13 Capturar la excepciónTypeError

<?php
declare(strict_types=1);

function
sum(int $a,int $b) {
return
$a+$b;
}

try {
var_dump(sum(1,2));
var_dump(sum(1.5,2.5));
} catch (
TypeError $e) {
echo
'Error: '.$e->getMessage();
}
?>

El resultado del ejemplo sería:

int(3)
Error: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 10

Listas de argumentos de longitud variable

PHP tiene soporte para listas de argumentos de longitud variable en funciones definidas por el usuario. Esto se implementa utilizando el token...en PHP 5.6 y posteriores, y utilizando las funcionesfunc_num_args(),func_get_arg(), yfunc_get_args()en PHP 5.5 y anteriores.

...en PHP 5.6+

En PHP 5.6 y posteriores, las listas de argumentos pueden incluir el token...para denotar que la función acepta un número variable de argumentos. Los argumentos serán pasados a la variable dada como un aryay, por ejemplo:

Ejemplo #14 Usando...para acceder a argumentos variables

<?php
functionsum(...$números) {
$acc=0;
foreach (
$númerosas$n) {
$acc+=$n;
}
return
$acc;
}

echo
sum(1,2,3,4);
?>

El resultado del ejemplo sería:

10

También se puede emplear...al llamar a funciones para convertir unarrayo variableTraversableo literal en una lista de argumentos:

Ejemplo #15 Usar...para proporcionar argumentos

<?php
functionadd($a,$b) {
return
$a+$b;
}

echo
add(...[1,2])."\n";

$a= [1,2];
echo
add(...$a);
?>

El resultado del ejemplo sería:

3
3

Se puede especifcar argumentos posicionales normales antes del token.... En este caso, solamente los argumentos al final que no coincidan con un argumento posicional serán añadidos al array generado por....

También es posible añadir unadeclaración de tipoantes del símbolo.... Si está presente, todos los argumentos capturados por...deben ser objetos de la clase implicada.

Ejemplo #16 Argumentos variables de declaración de tipo

<?php
functiontotal_intervals($unit,DateInterval...$intervals) {
$time=0;
foreach (
$intervalsas$interval) {
$time+=$interval->$unit;
}
return
$time;
}

$a= newDateInterval('P1D');
$b= newDateInterval('P2D');
echo
total_intervals('d',$a,$b).' days';

// Esto fallará, debido a que null no es un objeto de DateInterval.
echototal_intervals('d',null);
?>

El resultado del ejemplo sería:

3 days
Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2

Por último, también es pueden pasar argumentos variablespor referenciaprefijando...con el signo (&).

Versiones antiguas de PHP

No se requiere una sintaxis especial para señalar que una función es varíadica; sin embargo, para acceder a los argumentos de la función se debe usarfunc_num_args(),func_get_arg()yfunc_get_args().

El primer ejemplo de antes se implementaría en PHP 5.5 y anteriores como sigue:

Ejemplo #17 Acceder a argumentos variables en PHP 5.5 y anteriores

<?php
functionsum() {
$acc=0;
foreach (
func_get_args() as$n) {
$acc+=$n;
}
return
$acc;
}

echo
sum(1,2,3,4);
?>

El resultado del ejemplo sería:

10

Named Arguments

PHP 8.0.0 introduced named arguments as an extension of the existing positional parameters. Named arguments allow passing arguments to a function based on the parameter name, rather than the parameter position. This makes the meaning of the argument self-documenting, makes the arguments order-independent and allows skipping default values arbitrarily.

Named arguments are passed by prefixing the value with the parameter name followed by a colon. Using reserved keywords as parameter names is allowed. The parameter name must be an identifier, specifying dynamically is not allowed.

Ejemplo #18 Named argument syntax

<?php
myFunction
(paramName:$value);
array_foobar(array:$value);

// NOT supported.
function_name($variableStoringParamName:$value);
?>

Ejemplo #19 Positional arguments versus named arguments

<?php
// Using positional arguments:
array_fill(0,100,50);

// Using named arguments:
array_fill(start_index:0,count:100,value:50);
?>

The order in which the named arguments are passed does not matter.

Ejemplo #20 Same example as above with a different order of parameters

<?php
array_fill
(value:50,num:100,start_index:0);
?>

Named arguments can be combined with positional arguments. In this case, the named arguments must come after the positional arguments. It is also possible to specify only some of the optional arguments of a function, regardless of their order.

Ejemplo #21 Combining named arguments with positional arguments

<?php
htmlspecialchars
($string,double_encode:false);
// Same as
htmlspecialchars($string,ENT_COMPAT|ENT_HTML401,'UTF-8',false);
?>

Passing the same parameter multiple times results in an Error exception.

Ejemplo #22 Error exception when passing the same parameter multiple times

<?php
functionfoo($param) { ... }

foo(param:1,param:2);
// Error: Named parameter $param overwrites previous argument
foo(1,param:2);
// Error: Named parameter $param overwrites previous argument
?>


Devolver valores

Los valores son devueltos usando la sentencia opcional return. Se puede devolver cualquier tipo, incluidos arrays y objetos. Esto causa que la función finalice su ejecución inmediatamente y pase el control de nuevo a la línea desde la que fue llamada. Véasereturnpara más información.

Nota:

Si se omitereturn, el valor devuelto seránull.

Empleo de return

Ejemplo #1 Empleo dereturn

<?php
functioncuadrado($núm)
{
return
$núm*$núm;
}
echo
cuadrado(4);// imprime '16'.
?>

Una función no puede devolver múltiples valores, pero se pueden obtener resultados similares devolviendo un array.

Ejemplo #2 Devolver un array para obtener múltiples valores

<?php
functionnúmeros_pequeños()
{
return array (
0,1,2);
}
list (
$cero,$uno,$dos) =números_pequeños();
?>

Para devolver una referencia desde una función use el operador de referencia &, en la declaración de la función y cuando se asigne el valor devuelto a una variable:

Ejemplo #3 Devolver una referencia desde una función

<?php
function &devolver_referencia()
{
return
$algunaref;
}

$nuevaref=&devolver_referencia();
?>

Para más información sobre referencias, por favor, lea lasReferencias explicadas.

Declaraciones de tipo de devolución

PHP 7 añade soporte para las declaraciones de tipo de devolución. De forma similar a lasdeclaraciones de tipo de argumento, las declaraciones de tipo de devolución especifican el tipo del valor que serán devuelto desde una función. Están disponibles los mismostipospara las declaraciones de tipo de devolución que para las declaraciones de tipo de argumento.

Latipificación estrictatambién tiene efecto sobre las declaraciones de tipo de devolución. En el modo predeterminado de tipificacón débil, los valores devueltos serán forzados al tipo correcto si no son ya de ese tipo. En el modo fuerte, el valor devuelto debe ser del tipo correcto, o de lo contrario se lanzará una excepciónTypeError.

A partir de PHP 7.1.0, los valores de retorno pueden ser marcados como anulables anteponiendo el prefijo nombre de tipo con un signo de interrogación (?). Esto significa que la función devuelve el tipo especificado onull.

Nota:

Al sobrescribir un método padre, el método hijo debe hacer coincidir cualquier declaración de tipo de devolución del padre. Si el padre no define un tipo de devolución, el método hijo puede hacerlo.

Ejemplos

Ejemplo #4 Declaración básica de tipo de devolución

<?php
functionsum($a,$b):float{
return
$a+$b;
}

// Observe que será devuelto un float.
var_dump(sum(1,2));
?>

El resultado del ejemplo sería:

float(3)

Ejemplo #5 El modo estricto en acción

<?php
declare(strict_types=1);

function
sum($a,$b):int{
return
$a+$b;
}

var_dump(sum(1,2));
var_dump(sum(1,2.5));
?>

El resultado del ejemplo sería:

int(3)

Fatal error: Uncaught TypeError: Return value of sum() must be of the type integer, float returned in - on line 5 in -:5
Stack trace:
#0 -(9): sum(1, 2.5)
#1 {main}
  thrown in - on line 5

Ejemplo #6 Devolver un objeto

<?php
classC{}

function
getC():C{
return new
C;
}

var_dump(getC());
?>

El resultado del ejemplo sería:

object(C)#1 (0) {
}

Ejemplo #7 Declaración de tipo de retorno anulable (a partir de PHP 7.1.0)

<?php
functionget_item(): ?string{
if (isset(
$_GET['item'])) {
return
$_GET['item'];
} else {
return
null;
}
}
?>


Funciones variables

PHP admite el concepto de funciones variables. Esto significa que si un nombre de variable tiene paréntesis anexos a él, PHP buscará una función con el mismo nombre que lo evaluado por la variable, e intentará ejecutarla. Entre otras cosas, esto se puede usar para implementar llamadas de retorno, tablas de funciones, y así sucesivamente.

Las funciones variables no funcionarán con constructores de lenguaje comoecho,print,unset(),isset(),empty(),include,requirey similares. Utilice funciones de envoltura para hacer uso de cualquiera de estos constructores como funciones variables.

Ejemplo #1 Ejemplo de función variable

<?php
functionfoo() {
echo
"En foo()<br />\n";
}

function
bar($arg='')
{
echo
"En bar(); el argumento era '$arg'.<br />\n";
}

// Esta es una función de envoltura alrededor de echo
functionhacerecho($cadena)
{
echo
$cadena;
}

$func='foo';
$func();// Esto llama a foo()

$func='bar';
$func('prueba');// Esto llama a bar()

$func='hacerecho';
$func('prueba');// Esto llama a hacerecho()
?>

Los métodos de objetos también puede ser llamados con la sintaxis de funciones variables.

Ejemplo #2 Ejemplo de método variable

<?php
classFoo
{
function
Variable()
{
$nombre='Bar';
$this->$nombre();// Esto llama al método Bar()
}

function
Bar()
{
echo
"Esto es Bar";
}
}

$foo= newFoo();
$nombrefunc="Variable";
$foo->$nombrefunc();// Esto llama a $foo->Variable()

?>

Cuando se llaman a métodos estáticos, la llamada a la función es más fuerte que el operador de propiedad estática:

Ejemplo #3 Ejemplo de método variable con propiedades estáticas

<?php
classFoo
{
static
$variable='propiedad estática';
static function
Variable()
{
echo
'Método Variable llamado';
}
}

echo
Foo::$variable;// Esto imprime 'propiedad estática'. No necesita una $variable en este ámbito.
$variable="Variable";
Foo::$variable();// Esto llama a $foo->Variable() leyendo $variable en este ámbito.

?>

A partir de PHP 5.4.0, se puede llamar a cualquiercallablealmacenado en una variable.

Ejemplo #4 Llamables complejos

<?php
classFoo
{
static function
bar()
{
echo
"bar\n";
}
function
baz()
{
echo
"baz\n";
}
}

$func= array("Foo","bar");
$func();// imprime "bar"
$func= array(newFoo,"baz");
$func();// imprime "baz"
$func="Foo::bar";
$func();// imprime "bar" a partrid de PHP 7.0.0; antes, emitía un error fatal
?>

Véase tambiénis_callable(),call_user_func(),variables variablesyfunction_exists().

Historial de cambios

VersiónDescripción
7.0.0'NombreDeClase::NombreDeMétodo' se permite como función variable.
5.4.0Los arrays, que son llamables válidos, están permitidos como funciones variables.



Funciones internas (incluidas)

PHP se estandariza con muchas funciones y construcciones. También existen funciones que necesitan extensiones específicas de PHP compiladas, si no, aparecerán errores fatales "undefined function" ("función no definida"). Por ejemplo, para usar las funciones deimagetales comoimagecreatetruecolor(), PHP debe ser compilado con soporte paraGD. O para usarmysql_connect(), PHP debe ser compilado con soporte paraMySQLi. Hay muchas funciones de núcleo que está incluidas en cada versión de PHP, tales como las funciones destringy devariable. Una llamada aphpinfo()oget_loaded_extensions()mostrará las extensiones que están cargadas en PHP. Observe también que muchas extensiones están habilitadas por defecto y que el manual de PHP está dividido por extensiones. Véaseconfiguración,instalación, y capítulos individuales de extensiones para más información sobre cómo configurar PHP.

Interpretar y comprender un prototipo de una función está explicado dentro de la sección del manual tituladacómo interpretar la definición de una función. Es importante comprender lo que devuelve una función o si una función funciona directamente con un valor pasado. Por ejemplo,str_replace()devolverá la cadena modificada mientras queusort()funciona con la variable actual pasada. Cada página del manual también tiene información específica para cada función, como información sobre parámetros de funciones, cambios de comportamiento, valores devueltos en caso de éxito o fallo, e información de disponibilidad. Conocer estas importantes diferencias (a menudo imperceptibles) es crucial para escribir código de PHP correcto.

Nota:Si los parámetros dados a una función no son los que se esperaban, como pasar unarraydonde se esperaba unstring, el valor devuelto de la función será indefinido. En este caso lo más probable es que devuelvanullpero esto es sólo una convención, y no se puede confiar en ello.

Véase tambiénfunction_exists(),la referencia de funciones,get_extension_funcs(), ydl().



Funciones anónimas

Las funciones anónimas, también conocidas comocierres(closures), permiten la creación de funciones que no tienen un nombre especificado. Son más útiles como valor de los parámetros dellamadas de retorno, pero tienen muchos otros usos.

Las funciones anónimas están implementadas utilizando la claseClosure.

Ejemplo #1 Ejemplo de función anónima

<?php
echopreg_replace_callback('~-([a-z])~', function ($coincidencia) {
return
strtoupper($coincidencia[1]);
},
'hola-mundo');
// imprime holaMundo
?>

Los cierres también se pueden usar como valores de variables; PHP automáticamente convierte tales expresiones en instancias de la clase internaClosure. La asignación de un cierre a una variable emplea la misma sintaxis que cualquier otra asignación, incluido el punto y coma final:

Ejemplo #2 Ejemplo de asignación de variable de una función anónima

<?php
$saludo
= function($nombre)
{
printf("Hola %s\r\n",$nombre);
};

$saludo('Mundo');
$saludo('PHP');
?>

Los cierres también pueden heredar variables del ámbito padre. Cualquier variable debe ser pasada al constructor de lenguajeuse. Desde PHP 7.1, estas variables no deben incluirsuperglobals,$this, o variables con el mismo nombre que un parámetro.

Ejemplo #3 Heredar variables de un ámbito padre

<?php
$mensaje
='hola';

// Sin "use"
$ejemplo= function () {
var_dump($mensaje);
};
$ejemplo();

// Heredar $mensaje
$ejemplo= function () use ($mensaje) {
var_dump($mensaje);
};
$ejemplo();

// El valor de la variable heredada está cuando la función
// está definida, no cuando se le invoca
$mensaje='mundo';
$ejemplo();

// Reiniciar el mensaje
$mensaje='hola';

// Heredar por referencia
$ejemplo= function () use (&$mensaje) {
var_dump($mensaje);
};
$ejemplo();

// El valor cambiado en el ámbito padre
// se refleja dentro de la llamada a la función
$mensaje='mundo';
$ejemplo();

// Los cierres también aceptan argumentos normales
$ejemplo= function ($arg) use ($mensaje) {
var_dump($arg.' '.$mensaje);
};
$ejemplo("hola");
?>

El resultado del ejemplo sería algo similar a:

Notice: Undefined variable: message in /example.php on line 6
NULL
string(4) "hola"
string(4) "hola"
string(4) "hola"
string(5) "mundo"
string(10) "hola mundo"

Heredar variables del ámbito padrenoes lo mismo que usar variables globales. Las variables globales existen en el ámbito global, lo que implica que no importa qué función se esté ejecutando. El ámbito padre de un cierre es la función en la que dicho cierre fue declarado (no necesariamente la función desde la que se llamó). Vea el siguiente ejemplo:

Ejemplo #4 Cierres y ámbito

<?php
// Un carro de compras básico que contiene una lista de productos añadidos
// y la cantidad de cada producto. Incluye un método que
// calcula el precio total de los artículos del carro usando un
// cierre como llamada de retorno.
classCarro
{
const
PRECIO_MANTEQUILLA=1.00;
const
PRECIO_LECHE=3.00;
const
PRECIO_HUEVOS=6.95;

protected
$productos= array();

public function
añadir($producto,$cantidad)
{
$this->productos[$producto] =$cantidad;
}

public function
obtenerCantidad($producto)
{
return isset(
$this->productos[$producto]) ?$this->productos[$producto] :
FALSE;
}

public function
obtenerTotal($impuesto)
{
$total=0.00;

$llamadaDeRetorno=
function (
$cantidad,$producto) use ($impuesto, &$total)
{
$precioUnidad=constant(__CLASS__."::PRECIO_".
strtoupper($producto));
$total+= ($precioUnidad*$cantidad) * ($impuesto+1.0);
};

array_walk($this->productos,$llamadaDeRetorno);
return
round($total,2);
}
}

$mi_carro= newCarro;

// Añadir algunos artículos al carro
$mi_carro->añadir('mantequilla',1);
$mi_carro->añadir('leche',3);
$mi_carro->añadir('huevos',6);

// Imprimir el total con un impuesto de venta del 5%.
print$mi_carro->obtenerTotal(0.05) ."\n";
// El resultado es 54.29
?>

Ejemplo #5 Vinculación automática de$this

<?php

classTest
{
public function
testing()
{
return function() {
var_dump($this);
};
}
}

$object= newTest;
$function=$object->testing();
$function();

?>

El resultado del ejemplo sería:

object(Test)#1 (0) {
}

Salida del ejemplo anterior en PHP 5.3:

Notice: Undefined variable: this in script.php on line 8
NULL

A partir de PHP 5.4.0, cuando se declara en el contexto de una clase, la clase actual está vinculada a ella automáticamente, haciendo que$thisesté disponible dentro del ámbito de la función. Si no se desea esta vinculación automática de la clase actual, se deberían usarfuncions anónimas estáticasen su lugar.

Static anonymous functions

A partir de PHP 5.4, las funciones anónimas pueden ser declaradas estáticamente. Esto evita tener la clase actual vinculada automáticamente a ellas. Los objetos tampoco podrían vincularse a ellas durante la ejecución.

Ejemplo #6 Intentar usar$thisdentro de una función anónima estática

<?php

classFoo
{
function
__construct()
{
$func= static function() {
var_dump($this);
};
$func();
}
};
new
Foo();

?>

El resultado del ejemplo sería:

Notice: Undefined variable: this in %s on line %d
NULL

Ejemplo #7 Intentar vincular un objeto a una función anónima estática

<?php

$func
= static function() {
// cuerpo de la función
};
$func=$func->bindTo(newStdClass);
$func();

?>

El resultado del ejemplo sería:

Warning: Cannot bind an instance to a static closure in %s on line %d

Historial de cambios

VersiónDescripción
7.1.0Las funciones anónimas no pueden tener un cierre sobresuperglobals,$this, o cualquier variable con el mismo nombre que un parámetro.
5.4.0Las funciones anónimas pueden usar$this, así como ser declaradas státicamente.
5.3.0Las funciones anónimas se encuentran disponibles.

Notas

Nota:Es posible utilizarfunc_num_args(),func_get_arg(), yfunc_get_args()desde dentro de un cierre.



Funciones de flecha

Las funciones de flecha fueron introducidas en PHP 7.4 como una sintaxis más concisa paralas funciones anónimas.

Tanto las funciones anónimas como las funciones de flecha se implementan utilizando la claseClosure.

Las funciones de las flechas tienen la forma básicafn (argument_list) => expr.

Las funciones de las flechas soportan las mismas características quelas funciones anónimas, excepto que el uso de variables del ámbito padre siempre es automático.

Cuando una variable utilizada en la expresión se define en el ámbito padre será implícitamente capturada por valor. En el siguiente ejemplo, las funciones$fn1y$fn2se comportan de la misma manera.

Ejemplo #1 Las funciones de flecha capturan las variables por valor automáticamente

<?php

$y
=1;

$fn1=fn($x) =>$x+$y;
// equivalent to using $y by value:
$fn2= function ($x) use ($y) {
return
$x+$y;
};

var_export($fn1(3));
?>

El resultado del ejemplo sería:

4

Esto también funciona si las funciones de la flecha están anidadas:

Ejemplo #2 Las funciones de flecha capturan variables por valor automáticamente, incluso cuando están anidadas

<?php

$z
=1;
$fn=fn($x) =>fn($y) =>$x*$y+$z;
// Outputs 51
var_export($fn(5)(10));
?>

De manera similar a las funciones anónimas, la sintaxis de la función de la flecha permite firmas de funciones arbitrarias, incluyendo los tipos de parámetros y de retorno, valores por defecto, variadades, así como por referencia al pasar y al regresar. Todos los siguientes son ejemplos válidos de las funciones de las flechas:

Ejemplo #3 Ejemplos de funciones de flecha

<?php

fn
(array$x) =>$x;
static
fn():int=>$x;
fn($x=42) =>$x;
fn(&$x) =>$x;
fn&($x) =>$x;
fn($x, ...$rest) =>$rest;

?>

Las funciones de flecha utilizan la unión variable por valor. Esto es aproximadamente equivalente a realizar unuse($x)para cada variable$xusada dentro de la función de la flecha. Una unión por valores significa que no es posible modificar ningún valor desde el ámbito exterior.Funciones anónimasse pueden utilizar en su lugar para las asignaciones por referencia.

Ejemplo #4 Los valores del alcance exterior no pueden ser modificados por las funciones de flecha

<?php

$x
=1;
$fn=fn() =>$x++;// No tiene ningún efecto
$fn();
var_export($x);// Salida 1

?>

Historial de cambios

VersiónDescripción
7.4.0Las funciones de flecha se hicieron disponibles.

Notas

Nota:Es posible utilizarfunc_num_args(),func_get_arg(), yfunc_get_args()desde dentro de una función de flecha.




Clases y objetos

Tabla de contenidos


Introducción

PHP incluye un modelo de objetos completo. Algunas de sus características son:visibilidad, clases y métodosabstractosyfinales,métodos mágicosadicionales,interfaces,clonación.

PHP trata los objetos de la misma manera que las referencias o manejadores, lo que significa que cada variable contiene una referencia a un objeto en lugar de una copia de todo el objeto. Véanse losObjetos y referencias



Lo básico

class

La definición básica de una clase comienza con la palabra reservadaclass, seguida de un nombre de clase, y continuando con un par de llaves que encierran las definiciones de las propiedades y métodos pertenecientes a dicha clase.

El nombre de clase puede ser cualquier etiqueta válida, siempre que no sea unapalabra reservadade PHP. Un nombre válido de clase comienza con una letra o un guión bajo, seguido de una cantidad arbitraria de letras, números o guiones bajos. Como expresión regular, se expresaría de la siguiente forma:^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$.

Una clase puede tener sus propiasconstantes,variables(llamadas "propiedades"), y funciones (llamados "métodos").

Ejemplo #1 Definición de una clase sencilla

<?php
classClaseSencilla
{
// Declaración de una propiedad
public$var='un valor predeterminado';

// Declaración de un método
public functionmostrarVar() {
echo
$this->var;
}
}
?>

La pseudovariable$thisestá disponible cuando un método es invocado dentro del contexto de un objeto.$thises una referencia al objeto invocador.

Advertencia

Llamar a un método no estático arroja estáticamente unError. Antes de PHP 8.0.0, esto generaría un aviso de desaprobación obsoleta, y$thisesto no estaría definido.

Ejemplo #2 Algunos ejemplos de la pseudovariable$this

<?php
classA
{
function
foo()
{
if (isset(
$this)) {
echo
'$this está definida (';
echo
get_class($this);
echo
")\n";
} else {
echo
"\$this no está definida.\n";
}
}
}

class
B
{
function
bar()
{
A::foo();
}
}

$a= newA();
$a->foo();

A::foo();

$b= newB();
$b->bar();

B::bar();
?>

Salida del ejemplo anterior en PHP 7:

$this está definida (A)

Deprecated: Non-static method A::foo() should not be called statically in %s  on line 27
$this is not defined.

Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
$this is not defined.

Deprecated: Non-static method B::bar() should not be called statically in %s  on line 32

Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
$this is not defined.

Output of the above example in PHP 8:

$this está definida (A)

Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27
Stack trace:
#0 {main}
  thrown in %s  on line 27

Readonly classes

As of PHP 8.2.0, a class can be marked with thereadonlymodifier. Marking a class asreadonlywill add thereadonlymodifierto every declared property, and prevent the creation ofdynamic properties. Moreover, it is impossible to add support for them by using theAllowDynamicPropertiesattribute. Attempting to do so will trigger a compile-time error.

<?php
#[AllowDynamicProperties]
readonlyclassFoo{
}

// Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo
?>

As neither untyped, nor static properties can be marked with thereadonlymodifier, readonly classes cannot declare them either:

<?php
readonly
classFoo
{
public
$bar;
}

// Fatal error: Readonly property Foo::$bar must have type
?>
<?php
readonly
classFoo
{
public static
int $bar;
}

// Fatal error: Readonly class Foo cannot declare static properties
?>

Areadonlyclass can beextendedif, and only if, the child class is also areadonlyclass.

new

Para crear una instancia de una clase, se debe emplear la palabra reservadanew. Un objeto se creará siempre a menos que el objeto tenga unconstructorque arroje unaexcepciónen caso de error. Las clases deberían ser definidas antes de la instanciación (y en algunos casos esto es un requerimiento).

Si se emplea unstringque contenga el nombre de una clase connew, se creará una nueva instancia de esa clase. Si la clase estuviera en un espacio de nombres, se debe utilizar su nombre completo al realizar esto.

Nota:

Si no hay argumentos para pasar al constructor de la clase, se pueden omitir los paréntesis después del nombre de la clase.

Ejemplo #3 Creación de una instancia

<?php
$instancia
= newClaseSencilla();

// Esto también se puede hacer con una variable:
$nombreClase='ClaseSencilla';
$instancia= new$nombreClase();// new ClaseSencilla()
?>

En el contexto de una clase, es posible crear un nuevo objeto connew selfynew parent.

Cuando se asigna una instancia ya creada de una clase a una nueva variable, ésta última accederá a la misma instancia que el objeto que le fue asignado. Esta conducta es la misma que cuando se pasan instancias a una función. Se puede realizar una copia de un objeto ya creado a través de laclonacióndel mismo.

Ejemplo #4 Asignación de objetos

<?php

$instancia
= newClaseSencilla();

$asignada=$instancia;
$referencia=&$instancia;

$instancia->var='$asignada tendrá este valor';

$instancia=null;// $instancia y $referencia son null

var_dump($instancia);
var_dump($referencia);
var_dump($asignada);
?>

El resultado del ejemplo sería:

NULL
NULL
object(ClaseSencilla)#1 (1) {
   ["var"]=>
     string(27) "$asignada tendrá este valor"
}

Existe un par de formas de crear instancias de un objecto:

Ejemplo #5 Creación de nuevos objetos

<?php
classPrueba
{
static public function
getNew()
{
return new static;
}
}

class
HijaextendsPrueba
{}

$obj1= newPrueba();
$obj2= new$obj1;
var_dump($obj1!==$obj2);

$obj3=Prueba::getNew();
var_dump($obj3instanceofPrueba);

$obj4=Hija::getNew();
var_dump($obj4instanceofHija);
?>

El resultado del ejemplo sería:

bool(true)
bool(true)
bool(true)

Es posible acceder a un miembro de un objeto recién creado en una única expresión:

Ejemplo #6 Acceder a un miembro de un objeto recién creado

<?php
echo (newDateTime())->format('Y');
?>

El resultado del ejemplo sería algo similar a:

2016

Nota:Antes de PHP 7.1, los argumentos no se evalúan si no hay una función constructora definida.

Propiedades y métodos

Las propiedades y métodos de una clase viven en «espacios de nombres» diferentes, por tanto, es posible tener una propiedad y un método con el mismo nombre. Al hacer referencia tanto a una propiedad como a un método se utiliza la misma notación, y si se accederá a la propiedad o se llamará al método, solamente depende del contexto, es decir, si el empleo es el acceso a una variable o la llamada a una función.

Ejemplo #7 Acceso a propiedad contra llamada a método

<?php
classFoo
{
public
$bar='property';

public function
bar() {
return
'method';
}
}

$obj= newFoo();
echo
$obj->bar,PHP_EOL,$obj->bar(),PHP_EOL;

El resultado del ejemplo sería:

propiedad
método

Esto significa que llamar a unafunción anónimaque ha sido asignada a una propiedad no es posible directamente. En su lugar, la propiedad ha de ser asignada primero a una variable, por ejemplo. A partir de PHP 7.0.0, es posible llamar a dicha propiedad directamente encerrándola entre paréntesis.

Ejemplo #8 Llamar a una función anónima almacenada en una propiedad

<?php
classFoo
{
public
$bar;

public function
__construct() {
$this->bar= function() {
return
42;
};
}
}

$obj= newFoo();

echo (
$obj->bar)(),PHP_EOL;

El resultado del ejemplo sería:

42

extends

Una clase puede heredar los métodos y propiedades de otra clase empleando la palabra reservadaextendsen la declaración de la clase. No es posible la extensión de múltiples clases; una clase sólo puede heredar de una clase base.

Los métodos y propiedades heredados pueden ser sobrescritos con la redeclaración de éstos utilizando el mismo nombre que en la clase madre. Sin embargo, si la clase madre definió un método comofinal, éste no podrá ser sobrescrito. Es posible acceder a los métodos sobrescritos o a las propiedades estáticas haciendo referencia a ellos conparent::.

Ejemplo #9 Herencia de clases sencilla

<?php
classClaseExtendidaextendsClaseSencilla
{
// Redefinición del método padre
functionmostrarVar()
{
echo
"Clase extendida\n";
parent::mostrarVar();
}
}

$extendida= newClaseExtendida();
$extendida->mostrarVar();
?>

El resultado del ejemplo sería:

Clase extendida
un valor predeterminado

Signature compatibility rules

When overriding a method, its signature must be compatible with the parent method. Otherwise, a fatal error is emitted, or, prior to PHP 8.0.0, anE_WARNINGlevel error is generated. A signature is compatible if it respects thevariancerules, makes a mandatory parameter optional, and if any new parameters are optional. This is known as the Liskov Substitution Principle, or LSP for short. Theconstructor, andprivatemethods are exempt from these signature compatibility rules, and thus won't emit a fatal error in case of a signature mismatch.

Ejemplo #10 Compatible child methods

<?php

classBase
{
public function
foo(int $a) {
echo
"Valid\n";
}
}

class
Extend1extendsBase
{
function
foo(int $a=5)
{
parent::foo($a);
}
}

class
Extend2extendsBase
{
function
foo(int $a,$b=5)
{
parent::foo($a);
}
}

$extended1= newExtend1();
$extended1->foo();
$extended2= newExtend2();
$extended2->foo(1);

El resultado del ejemplo sería:

Valid
Valid

The following examples demonstrate that a child method which removes a parameter, or makes an optional parameter mandatory, is not compatible with the parent method.

Ejemplo #11 Fatal error when a child method removes a parameter

<?php

classBase
{
public function
foo(int $a=5) {
echo
"Valid\n";
}
}

class
ExtendextendsBase
{
function
foo()
{
parent::foo(1);
}
}

Output of the above example in PHP 8 is similar to:

Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

Ejemplo #12 Fatal error when a child method makes an optional parameter mandatory

<?php

classBase
{
public function
foo(int $a=5) {
echo
"Valid\n";
}
}

class
ExtendextendsBase
{
function
foo(int $a)
{
parent::foo($a);
}
}

Output of the above example in PHP 8 is similar to:

Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13
Advertencia

Renaming a method's parameter in a child class is not a signature incompatibility. However, this is discouraged as it will result in a runtimeErrorifnamed argumentsare used.

Ejemplo #13 Error when using named arguments and parameters were renamed in a child class

<?php

classA{
public function
test($foo,$bar) {}
}

class
BextendsA{
public function
test($a,$b) {}
}

$obj= newB;

// Pass parameters according to A::test() contract
$obj->test(foo:"foo",bar:"bar");// ERROR!

El resultado del ejemplo sería algo similar a:

Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
Stack trace:
#0 {main}
  thrown in /in/XaaeN on line 14

::class

La palabra reservadaclasses usada para la resolución de nombres de clases. Se puede obtener un string con el nombre completamente cualificado de la claseClassNameutilizandoClassName::class. Esto es particularmete útil con clases enespacios de nombres.

Ejemplo #14 Resolución de nombres de clases

<?php
namespaceNS{
class
ClassName{
}

echo
ClassName::class;
}
?>

El resultado del ejemplo sería:

NS\ClassName

Nota:

La resolución de nombres de clases con::classes una transformación durante la compilación. Esto significa que, en el instante de crear el string del nombre de la clase, aún no se ha realizado ninguna autocarga. Como consecuencia, los nombres de clases se expanden incluso si la clase no existe. No se emite ningún error en tal caso.

Ejemplo #15 Missing class name resolution

<?php
printDoes\Not\Exist::class;
?>

El resultado del ejemplo sería:

Does\Not\Exist

As of PHP 8.0.0, the::classconstant may also be used on objects. This resolution happens at runtime, not compile time. Its effect is the same as callingget_class()on the object.

Ejemplo #16 Object name resolution

<?php
namespaceNS{
class
ClassName{
}
}
$c= newClassName();
print
$c::class;
?>

El resultado del ejemplo sería:

NS\ClassName

Nullsafe methods and properties

As of PHP 8.0.0, properties and methods may also be accessed with the "nullsafe" operator instead:?->. The nullsafe operator works the same as property or method access as above, except that if the object being dereferenced isnullthennullwill be returned rather than an exception thrown. If the dereference is part of a chain, the rest of the chain is skipped.

The effect is similar to wrapping each access in anis_null()check first, but more compact.

Ejemplo #17 Nullsafe Operator

<?php

// As of PHP 8.0.0, this line:
$result=$repository?->getUser(5)?->name;

// Is equivalent to the following code block:
if (is_null($repository)) {
$result=null;
} else {
$user=$repository->getUser(5);
if (
is_null($user)) {
$result=null;
} else {
$result=$user->name;
}
}
?>

Nota:

The nullsafe operator is best used when null is considered a valid and expected possible value for a property or method return. For indicating an error, a thrown exception is preferable.



Propiedades

Las variables pertenecientes a una clase se llamanpropiedades. También se les puede llamar usando otros términos comoatributos, ocampos, pero para los propósitos de esta referencia se va a utilizarpropiedades. Éstas se definen usando una de las palabras reservadaspublic,protected, oprivate, opcionalmente, a partir de PHP 7.4, seguido de una declaración de tipo, seguida de una declaración de variable normal. Esta declaración puede incluir una inicialización, pero esta inicialización debe ser un valor deconstante.

Véase laVisibilidadpara más información sobre el significado depublic,protected, yprivate.

Nota:

Como alternativa y no recomendada de declarar las propiedades de una clase, ya que es para mantener la compatibilidad con PHP 4, se acepta el uso de la palabra reservadavar. Esta tratará la propiedad de forma idéntica a como se hubiera declarado comopublic.

Dentro de los métodos de una clase, se puede acceder a las propiedades no estáticas utilizando->(el operador de objeto):$this->propiedad(dondepropiedades el nombre de la propiedad). A las propiedades estáticas se puede acceder utilizando::(doble dos puntos):self::$propiedad. Véasela palabra reservada 'static'para más información sobre la diferencia entre propiedades estáticas y no estáticas.

La pseudovariable$thisestá disponible dentro de cualquier método de clase cuando éste es invocado dentro del contexto de un objeto.$thises una referencia al objeto invocador (usualmente el objeto al cual pertenece el método, aunque puede que sea otro objeto si el método es llamadoestáticamentedesde el contexto de un objeto secundario).

Ejemplo #1 Declaración de propiedades

<?php
classClaseSencilla
{
public
$var1='hola '.'mundo';
public
$var2= <<<EOD
hola mundo
EOD;
public
$var3=1+2;
// Declaraciones de propiedades inválidas:
public$var4=self::miMetodoEstatico();
public
$var5=$myVar;

// Declaraciones de propiedades válidas:
public$var6=miConstante;
public
$var7= [true,false];

public
$var8= <<<'EOD'
hola mundo
EOD;
}
?>

Nota:

Existen varias funciones para manipular clases y objetos. VéaseLas funciones de clases/objetos.

Declaraciones de tipo

A partir de PHP 7.4.0, las definiciones de propiedades pueden incluirseDeclaraciones de tipo, con la excepción de loscallable.

Ejemplo #2 Ejemplo de propiedades tipadas

<?php

classUser
{
public
int $id;
public ?
string $name;

public function
__construct(int $id, ?string $name)
{
$this->id=$id;
$this->name=$name;
}
}

$user= newUser(1234,null);

var_dump($user->id);
var_dump($user->name);

?>

El resultado del ejemplo sería:

int(1234)
NULL

Las propiedades tipadas deben ser inicializadas antes de acceder a ellas, de lo contrario se produce unError.

Ejemplo #3 Acceso a las propiedades

<?php

classShape
{
public
int $numberOfSides;
public
string $name;

public function
setNumberOfSides(int $numberOfSides):void
{
$this->numberOfSides=$numberOfSides;
}

public function
setName(string $name):void
{
$this->name=$name;
}

public function
getNumberOfSides():int
{
return
$this->numberOfSides;
}

public function
getName():string
{
return
$this->name;
}
}

$triangle= newShape();
$triangle->setName("triangle");
$triangle->setNumberofSides(3);
var_dump($triangle->getName());
var_dump($triangle->getNumberOfSides());

$circle= newShape();
$circle->setName("circle");
var_dump($circle->getName());
var_dump($circle->getNumberOfSides());
?>

El resultado del ejemplo sería:

string(8) "triangle"
int(3)
string(6) "circle"

Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization

Propiedad Readonly

A partir de PHP 8.1.0, una propiedad se puede declarar con el modificadorreadonly(de solo lectura), lo que impide la modificación de la propiedad después de la inicialización.

Ejemplo #4 Ejemplo de propiedades de solo lectura

<?php

classTest{
public
readonly string $prop;

public function
__construct(string $prop) {
// Inicialización.
$this->prop=$prop;
}
}

$test= newTest("foobar");
// Lectura.
var_dump($test->prop);// string(6) "foobar"

// Reasignación ilegal. No importa que el valor asignado sea el mismo.
$test->prop="foobar";
// Error: Cannot modify readonly property Test::$prop
?>

Nota:

El modificador readonly solo se puede aplicar a laspropiedades tipadas. Se puede crear una propiedad readonly sin restricciones mediante el tipomixed.

Nota:

El modificador readonly no son compatibles en propiedades estáticas.

Una propiedad readonly solo se puede inicializar una vez, y solo desde el ámbito en el que se ha declarado. Cualquier otra asignación o modificación de la propiedad dará lugar a una excepción deError.

Ejemplo #5 Inicialización ilegal de propiedades readonly

<?php
classTest1{
public
readonly string $prop;
}

$test1= newTest1;
// Inicialización ilegal fuera del ámbito privado.
$test1->prop="foobar";
// Error: Cannot initialize readonly property Test1::$prop from global scope
?>

Nota:

No se permite especificar un valor predeterminado explícito en las propiedades readonly, porque una propiedad readonly con un valor predeterminado es esencialmente la misma que una constante y, por lo tanto, no es particularmente útil.

<?php

classTest{
// Fatal error: Readonly property Test::$prop cannot have default value
publicreadonly int $prop=42;
}
?>

Nota:

Las propiedades readonly no pueden usarse con la funciónunset()una vez inicializadas. Sin embargo, es posible desactivar una propiedad readonly antes de la inicialización, desde el ámbito donde se ha declarado la propiedad.

Las modificaciones no son necesariamente asignaciones simples, todo lo siguiente también dará lugar a una excepciónError:

<?php

classTest{
public function
__construct(
public
readonly int $i=0,
public
readonlyarray$ary= [],
) {}
}

$test= newTest;
$test->i+=1;
$test->i++;
++
$test->i;
$test->ary[] =1;
$test->ary[0][] =1;
$ref=&$test->i;
$test->i=&$ref;
byRef($test->i);
foreach (
$testas &$prop);
?>

Sin embargo, las propiedades readonly no excluyen la mutabilidad interior. Los objetos (o recursos) almacenados en propiedades readonly aún pueden modificarse internamente:

<?php

classTest{
public function
__construct(publicreadonly object $obj) {}
}

$test= newTest(newstdClass);
// Mutación interior.
$test->obj->foo=1;
// Reasignación ilegal.
$test->obj= newstdClass;
?>

Dynamic properties

If trying to assign to a non existant property on anobject, PHP will automatically create a corresponding property. This dynamically created property willonlybe available on this class instance.

Advertencia

Dynamic properties are deprecated as of PHP 8.2.0. It is recommended to declare the property instead. To handle arbitrary property names, the class should implement the magic methods__get()and__set(). At last resort the class can be marked with the#[\AllowDynamicProperties]attribute.



Constantes de clases

Es posible definir valores constantes en función de cada clase manteniéndola invariable. Las constantes se diferencian de las variables comunes en que no utilizan el símbolo$al declararlas o emplearlas. La visibilidad predeterminada de las constantes de clase espublic.

El valor debe ser una expresión constante, no (por ejemplo) una variable, una propiedad o una llamada a una función.

También es posible que las interfaces tenganconstantes. Consulte los ejemplos de ladocumentación de interfaces.

A partir de PHP 5.3.0, es posible referirse a una clase utilizando una variable. El valor de la variable no puede ser una palabra reservada (p.ej.,self,parentostatic).

Observe que las constantes de clase están asignadas una vez por clase, y no por cada instancia de la clase.

Ejemplo #1 Definición y uso de una constante

<?php
classMiClase
{
const
CONSTANTE='valor constante';

function
mostrarConstante() {
echo
self::CONSTANTE."\n";
}
}

echo
MiClase::CONSTANTE."\n";

$nombreclase="MiClase";
echo
$nombreclase::CONSTANTE."\n";// A partir de PHP 5.3.0

$clase= newMiClase();
$clase->mostrarConstante();

echo
$clase::CONSTANTE."\n";// A partir de PHP 5.3.0
?>

Ejemplo #2 Ejemplo de datos estáticos

<?php
classfoo{
// A partir de PHP 5.3.0
constBAR= <<<'EOT'
bar
EOT;
// A partir de PHP 5.3.0
constBAZ= <<<EOT
baz
EOT;
}
?>

Nota:

El soporte para la inicialización de constantes con la sintaxis de Heredoc y Nowdoc fue agregado en PHP 5.3.0.

La constante especial::classestá disponible a partir de PHP 5.5.0, y permite la resolución de nombres de clase completamente cualificados en la compilación. Esto es útil para clases en espacios de nombres:

Ejemplo #3 Ejemplo de ::class en espacio de nombres

<?php
namespacefoo{
class
bar{
}

echo
bar::class;// foo\bar
}
?>

Ejemplo #4 Ejemplo de expresión constante

<?php
constUNO=1;

class
foo{
// A partir de PHP 5.6.0
constDOS=UNO*2;
const
TRES=UNO+self::DOS;
const
SENTENCIA='El valor de TRES es '.self::TRES;
}
?>

Es posible proporcionar una expresión escalar que implique literales numéricos y de string y/o constantes en el contexto de una constante de clase.

Nota:

El soporte para expresiones constantes se añadió en PHP 5.6.0.

Ejemplo #5 Modificadores de visibilidad de constantes de clase

<?php
classFoo{
// A partir de PHP 7.1.0
public constBAR='bar';
private const
BAZ='baz';
}
echo
Foo::BAR,PHP_EOL;
echo
Foo::BAZ,PHP_EOL;
?>

Salida del ejemplo anterior en PHP 7.1:

bar

Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in …

Nota:

A partir de PHP 7.1.0, están permitidos los modificadores de visibilidad para constantes de clase.



Autocarga de clases

Muchos desarrolladores que escriben aplicaciones orientadas a objetos crean un fichero fuente de PHP para cada definición de clase. Una de las mayores molestias es tener que hacer una larga lista de inclusiones al comienzo de cada script (uno por cada clase).

En PHP 5 esto ya no es necesario. La funciónspl_autoload_register()registra cualquier número de autocargadores, posibilitando que las clases e interfaces sean cargadas automáticamente si no están definidas actualmente. Al registrar autocargadores, a PHP se le da una última oportunidad de cargar las clases o interfaces antes de que falle por un error.

Sugerencia

Aunque la función__autoload()también puede ser empleada para autocargar clases e interfaces, es preferible utilizar la funciónspl_autoload_register(). Esto es debido a que es una alternativa más flexible (posibilitando que se pueda especificar cualquier número de autocargadores en la aplicación, tales como los de las bibliotecas de terceros). Por esta razón, se desaconseja el uso de__autoload()y es obsoleto a partir de PHP 7.2.0.

Nota:

Antes de 5.3.0, las excepciones lanzadas en la función__autoload()no podían ser capturadas en el bloquecatch, resultando en un error fatal. Desde 5.3 en adelante, esto es posible simpre que, si se lanza una excepción personalizada, esté disponible la clase de la excepción personalizada. La función__autoload()podría utilizarse recursivamente para cargar la clase de excepción personalizada.

Nota:

La autocarga no está disponible si se utiliza PHP en elmodo interactivoCLI.

Nota:

Si el nombre de la clase se utiliza, por ejemplo, encall_user_func(), este puede contener algunos caracteres peligrosos tales como../. Se recomienda no utilizar la entrada del usuario en tales funciones, o al menos verificar dicha entrada en__autoload().

Ejemplo #1 Ejemplo de autocarga

Este ejemplo intenta cargar las clasesMiClase1yMiClase2desde los ficherosMiClase1.phpyMiClase2.php, respectivamente.

<?php
spl_autoload_register
(function ($nombre_clase) {
include
$nombre_clase.'.php';
});

$obj= newMiClase1();
$obj2= newMiClase2();
?>

Ejemplo #2 Otro ejemplo de autocarga

Este ejemplo intenta cargar la interfazIPrueba.

<?php

spl_autoload_register
(function ($nombre) {
var_dump($nombre);
});

class
FooimplementsIPrueba{
}

/*
string(7) "IPrueba"

Fatal error: Interface 'IPrueba' not found in ...
*/
?>

Ejemplo #3 Autocarga con manejo de excepciones para 5.3.0+

Este ejemplo lanza una excepción y demuestra los bloques try/catch.

<?php
spl_autoload_register
(function ($nombre) {
echo
"Intentando cargar$nombre.\n";
throw new
Exception("Imposible cargar$nombre.");
});

try {
$obj= newClaseNoCargable();
} catch (
Exception $e) {
echo
$e->getMessage(),"\n";
}
?>

El resultado del ejemplo sería:

Intentando cargar ClaseNoCargable.
Imposible cargar ClaseNoCargable.

Ejemplo #4 Autocarga con manejo de excepciones para 5.3.0+: Excepción personalizada ausente

Este ejemplo lanza una excepción para una excepción personalizada no cargable.

<?php
spl_autoload_register
(function ($nombre) {
echo
"Intentando cargar$nombre.\n";
throw new
ExcepciónAusente("Imposible cargar$nombre.");
});

try {
$obj= newClaseNoCargable();
} catch (
Exception $e) {
echo
$e->getMessage(),"\n";
}
?>

El resultado del ejemplo sería:

Intentando cargar ClaseNoCargable.
Intentando cargar ExcepciónAusente.

Fatal error: Class 'ExcepciónAusente' not found in testExcepcionAusente.php on line 4



Constructores y destructores

Constructor

__construct(mixed...$values= ""):void

PHP permite a los desarrolladores declarar métodos constructores para las clases. Aquellas que tengan un método constructor lo invocarán en cada nuevo objeto creado, lo que lo hace idóneo para cualquier inicialización que el objeto pueda necesitar antes de ser usado.

Nota:Los constructores padres no son llamados implícitamente si la clase hija define un constructor. Para ejecutar un constructor padre, se requiere invocar aparent::__construct()desde el constructor hijo. Si el hijo no define un constructor, entonces se puede heredar de la clase madre como un método de clase normal (si no fue declarada como privada).

Ejemplo #1 Utilización de nuevos constructores unificados

<?php
classBaseClass{
function
__construct() {
print
"En el constructor BaseClass\n";
}
}

class
SubClassextendsBaseClass{
function
__construct() {
parent::__construct();
print
"En el constructor SubClass\n";
}
}

class
OtherSubClassextendsBaseClass{
// heredando el constructor BaseClass
}

// En el constructor BaseClass
$obj= newBaseClass();

// En el constructor BaseClass
// En el constructor SubClass
$obj= newSubClass();

// En el constructor BaseClass
$obj= newOtherSubClass();
?>

A diferencia de otros métodos,__construct()is exempt from the usualsignature compatibility ruleswhen being extended.

Constructors are ordinary methods which are called during the instantiation of their corresponding object. As such, they may define an arbitrary number of arguments, which may be required, may have a type, and may have a default value. Constructor arguments are called by placing the arguments in parentheses after the class name.

Ejemplo #2 Using constructor arguments

<?php
classPoint{
protected
int $x;
protected
int $y;

public function
__construct(int $x,int $y=0) {
$this->x=$x;
$this->y=$y;
}
}

// Pass both parameters.
$p1= newPoint(4,5);
// Pass only the required parameter. $y will take its default value of 0.
$p2= newPoint(4);
// With named parameters (as of PHP 8.0):
$p3= newPoint(y:5,x:4);
?>

If a class has no constructor, or the constructor has no required arguments, the parentheses may be omitted.

Old-style constructors

Prior to PHP 8.0.0, classes in the global namespace will interpret a method named the same as the class as an old-style constructor. That syntax is deprecated, and will result in anE_DEPRECATEDerror but still call that function as a constructor. If both__construct()and a same-name method are defined,__construct()will be called.

In namespaced classes, or any class as of PHP 8.0.0, a method named the same as the class never has any special meaning.

Always use__construct()in new code.

Constructor Promotion

As of PHP 8.0.0, constructor parameters may also be promoted to correspond to an object property. It is very common for constructor parameters to be assigned to a property in the constructor but otherwise not operated upon. Constructor promotion provides a short-hand for that use case. The example above could be rewritten as the following.

Ejemplo #3 Using constructor property promotion

<?php
classPoint{
public function
__construct(protectedint $x, protectedint $y=0) {
}
}

When a constructor argument includes a visibility modifier, PHP will interpret it as both an object property and a constructor argument, and assign the argument value to the property. The constructor body may then be empty or may contain other statements. Any additional statements will be executed after the argument values have been assigned to the corresponding properties.

Not all arguments need to be promoted. It is possible to mix and match promoted and not-promoted arguments, in any order. Promoted arguments have no impact on code calling the constructor.

Nota:

Object properties may not be typedcallabledue to engine ambiguity that would introduce. Promoted arguments, therefore, may not be typedcallableeither. Any othertype declarationis permitted, however.

Nota:

Attributes placed on a promoted constructor argument will be replicated to both the property and argument.

Static creation methods

PHP only supports a single constructor per class. In some cases, however, it may be desirable to allow an object to be constructed in different ways with different inputs. The recommended way to do so is by using static methods as constructor wrappers.

Ejemplo #4 Using static creation methods

<?php
classProduct{

private ?
int $id;
private ?
string $name;

private function
__construct(?int $id=null, ?string $name=null) {
$this->id=$id;
$this->name=$name;
}

public static function
fromBasicData(int $id,string $name): static {
$new= new static($id,$name);
return
$new;
}

public static function
fromJson(string $json): static {
$data=json_decode($json);
return new static(
$data['id'],$data['name']);
}

public static function
fromXml(string $xml): static {
// Put your own logic here.
$data=convert_xml_to_array($xml);
$new= new static();
$new->id=$data['id'];
$new->name=$data['name'];
return
$new;
}
}

$p1=Product::fromBasicData(5,'Widget');
$p2=Product::fromJson($some_json_string);
$p3=Product::fromXml($some_xml_string);

The constructor may be made private or protected to prevent it from being called externally. If so, only a static method will be able to instantiate the class. Because they are in the same class definition they have access to private methods, even if not of the same object instance. The private constructor is optional and may or may not make sense depending on the use case.

The three public static methods then demonstrate different ways of instantiating the object.

  • fromBasicData()takes the exact parameters that are needed, then creates the object by calling the constructor and returning the result.
  • fromJson()accepts a JSON string and does some pre-processing on it itself to convert it into the format desired by the constructor. It then returns the new object.
  • fromXml()accepts an XML string, preprocesses it, and then creates a bare object. The constructor is still called, but as all of the parameters are optional the method skips them. It then assigns values to the object properties directly before returning the result.

In all three cases, thestatickeyword is translated into the name of the class the code is in. In this case,Product.

Destructor

__destruct():void

PHP posee un concepto de destructor similar al de otros lenguajes orientados a objetos, tal como C++. El método destructor será llamado tan pronto como no hayan otras referencias a un objeto determinado, o en cualquier otra circunstancia de finalización.

Ejemplo #5 Ejemplo de Destructor

<?php

classMyDestructableClass
{
function
__construct() {
print
"En el constructor\n";
}

function
__destruct() {
print
"Destruyendo ".__CLASS__."\n";
}
}

$obj= newMyDestructableClass();

Como los constructores, los destructores padre no serán llamados implícitamente por el motor. Para ejecutar un destructor padre, se deberá llamar explícitamente aparent::__destruct()en el interior del destructor. También como los constructores, una clase child puede heredar el destructor de los padres si no implementa uno propio.

El destructor será invocado aún si la ejecución del script es detenida usandoexit(). Llamar aexit()en un destructor evitará que se ejecuten las rutinas restantes de finalización.

Nota:

Los destructores invocados durante la finalización del script tienen los headers HTTP ya enviados. El directorio de trabajo en la fase de finalización del script puede ser diferente con algunos SAPIs (por ej., Apache).

Nota:

Intentar lanzar una excepción desde un destructor (invocado en la finalización del script) causa un error fatal.



Visibilidad

La visibilidad de una propiedad, un método o (a partir de PHP 7.1.0) una constante se puede definir anteponiendo a su declaración una de las palabras reservadaspublic,protectedoprivate. A los miembros de clase declarados como 'public' se puede acceder desde donde sea; a los miembros declarados como 'protected', solo desde la misma clase, mediante clases heredadas o desde la clase padre. A los miembros declarados como 'private' únicamente se puede acceder desde la clase que los definió.

Visibilidad de propiedades

Las propiedades de clases deben ser definidas como 'public', 'private' o 'protected'. Si se declaran usandovar, serán definidas como 'public'.

Ejemplo #1 Declaración de propiedades

<?php
/**
* Definición de MyClass
*/
classMyClass
{
public
$public='Public';
protected
$protected='Protected';
private
$private='Private';

function
printHello()
{
echo
$this->public;
echo
$this->protected;
echo
$this->private;
}
}

$obj= newMyClass();
echo
$obj->public;// Funciona bien
echo$obj->protected;// Error Fatal
echo$obj->private;// Error Fatal
$obj->printHello();// Muestra Public, Protected y Private


/**
* Definición de MyClass2
*/
classMyClass2extendsMyClass
{
// Se pueden redeclarar las propiedades pública y protegida, pero no la privada
public$public='Public2';
protected
$protected='Protected2';

function
printHello()
{
echo
$this->public;
echo
$this->protected;
echo
$this->private;
}
}

$obj2= newMyClass2();
echo
$obj2->public;// Funciona bien
echo$obj2->protected;// Error Fatal
echo$obj2->private;// Undefined
$obj2->printHello();// Muestra Public2, Protected2, Undefined

?>

Nota:La forma de declaración de una variable de PHP 4 con la palabra clavevartodavía es soportado (como un sinónimo de public) por razones de compatibilidad. En PHP 5 antes de 5.1.3, su uso genera un WarningE_STRICT.

Visibilidad de Métodos

Los métodos de clases pueden ser definidos como public, private, o protected. Aquellos declarados sin ninguna palabra clave de visibilidad explícita serán definidos como public.

Ejemplo #2 Declaración de métodos

<?php
/**
* Definición de MyClass
*/
classMyClass
{
// Declaración de un constructor public
public function__construct() { }

// Declaración de un método public
public functionMyPublic() { }

// Declaración de un método protected
protected functionMyProtected() { }

// Declaración de un método private
private functionMyPrivate() { }

// Esto es public
functionFoo()
{
$this->MyPublic();
$this->MyProtected();
$this->MyPrivate();
}
}

$myclass= newMyClass;
$myclass->MyPublic();// Funciona
$myclass->MyProtected();// Error Fatal
$myclass->MyPrivate();// Error Fatal
$myclass->Foo();// Public, Protected y Private funcionan


/**
* Definición de MyClass2
*/
classMyClass2extendsMyClass
{
// Esto es public
functionFoo2()
{
$this->MyPublic();
$this->MyProtected();
$this->MyPrivate();// Error Fatal
}
}

$myclass2= newMyClass2;
$myclass2->MyPublic();// Funciona
$myclass2->Foo2();// Public y Protected funcionan, pero Private no

classBar
{
public function
test() {
$this->testPrivate();
$this->testPublic();
}

public function
testPublic() {
echo
"Bar::testPublic\n";
}

private function
testPrivate() {
echo
"Bar::testPrivate\n";
}
}

class
FooextendsBar
{
public function
testPublic() {
echo
"Foo::testPublic\n";
}

private function
testPrivate() {
echo
"Foo::testPrivate\n";
}
}

$myFoo= newFoo();
$myFoo->test();// Bar::testPrivate
// Foo::testPublic
?>

Visibilidad de las constantes

A partir de PHP 7.1.0, las constantes de clase se pueden definir como públicas, privadas o protegidas. Las constantes declaradas sin una visibilidad explítica serán definidas como públicas.

Ejemplo #3 Declaración de constantes a partir de PHP 7.1.0

<?php
/**
* Definir MiClase
*/
classMiClase
{
// Declarar una constante pública
public constMY_PUBLIC='public';

// Declarar una constante protegida
protected constMY_PROTECTED='protected';

// Declarar una constante privada
private constMY_PRIVATE='private';

public function
foo()
{
echo
self::MY_PUBLIC;
echo
self::MY_PROTECTED;
echo
self::MY_PRIVATE;
}
}

$myclass= newMiClase();
MiClase::MY_PUBLIC;// Funciona
MiClase::MY_PROTECTED;// Error fatal
MiClase::MY_PRIVATE;// Error fatal
$myclass->foo();// Funcionan Public, Protected y Private


/**
* Definir MiClase2
*/
classMiClase2extendsMiClase
{
// Esta es pública
functionfoo2()
{
echo
self::MY_PUBLIC;
echo
self::MY_PROTECTED;
echo
self::MY_PRIVATE;// Error fatal
}
}

$myclass2= newMiClase2;
echo
MiClase2::MY_PUBLIC;// Funciona
$myclass2->foo2();// Funcionan Public y Protected, pero no Private
?>

Visibilidad desde otros objetos

Los objetos del mismo tipo tendrán acceso a los miembros private y protected entre ellos aunque no sean de la misma instancia. Esto es porque los detalles específicos de implementación ya se conocen cuando se encuentra dentro de estos objetos.

Ejemplo #4 Accediendo a miembros private del mismo tipo de objeto

<?php
classTest
{
private
$foo;

public function
__construct($foo)
{
$this->foo=$foo;
}

private function
bar()
{
echo
'Método private accedido.';
}

public function
baz(Test $other)
{
// Se puede cambiar la propiedad private:
$other->foo='hola';
var_dump($other->foo);

// También se puede invocar al método private:
$other->bar();
}
}

$test= newTest('test');

$test->baz(newTest('other'));
?>

El resultado del ejemplo sería:

string(5) "hola"
Método private accedido.


Herencia de Objetos

La herencia es un principio de programación bien establecido y PHP hace uso de él en su modelado de objetos. Este principio afectará la manera en que muchas clases y objetos se relacionan unas con otras.

Por ejemplo, cuando se extiende una clase, la subclase hereda todos los métodos públicos y protegidos de la clase padre. A menos que una clase sobrescriba esos métodos, mantendrán su funcionalidad original.

Esto es útil para la definición y abstracción de la funcionalidad y permite la implementación de funcionalidad adicional en objetos similares sin la necesidad de reimplementar toda la funcionalidad compartida.

Los métodos privados de una clase padre no son accesibles para una clase hija. Como resultado, las clases hijas pueden reimplementar un método privado sin tener en cuenta las reglas de herencia normales. Antes de PHP 8.0.0, sin embargo, se aplicaban las restriccionesfinalystatica los métodos privados. A partir de PHP 8.0.0, la única restricción de métodos privados esprivate finalque se aplica en el constructor de la clase, ya que es una forma común de "deshabilitar" el constructor cuando es usado en métodos estáticos de fábrica (Patrón Factory).

Lavisibilidadde los métodos, propiedades y constantes pueden ser relajarse, por ejemplo, un méetodoprotectedpuede marcase comopublic, pero no pueden restringirse, por ejemplo. marcando una propiedadpubliccomoprivate.

Nota:

A menos que la carga automática sea utilizada, entonces las clases deben ser definidas antes de ser usadas. Si una clase se extiende a otra, entonces la clase padre debe ser declarada antes de la estructura de clase hija. Esta regla se aplica a las clases que heredan de otras clases e interfaces.

Nota:

No está permitido sobrescribir una propiedad de lectura-escritura con unapropiedad de sólo lecturao viceversa.

<?php

classA{
public
int $prop;
}
class
BextendsA{
// Ilegal: lectura-escritura -> sólo lectura
publicreadonly int $prop;
}
?>

Ejemplo #1 Ejemplo de herencia

<?php

classFoo
{
public function
printItem($string)
{
echo
'Foo: '.$string.PHP_EOL;
}

public function
printPHP()
{
echo
'PHP is great.'.PHP_EOL;
}
}

class
barextendsFoo
{
public function
printItem($string)
{
echo
'Bar: '.$string.PHP_EOL;
}
}

$foo= newFoo();
$bar= newBar();
$foo->printItem('baz');// Salida: 'Foo: baz'
$foo->printPHP();// Salida: 'PHP is great'
$bar->printItem('baz');// Salida: 'Bar: baz'
$bar->printPHP();// Salida: 'PHP is great'

?>

Return Type Compatibility with Internal Classes

Prior to PHP 8.1, most internal classes or methods didn't declare their return types, and any return type was allowed when extending them.

As of PHP 8.1.0, most internal methods started to "tentatively" declare their return type, in that case the return type of methods should be compatible with the parent being extended; otherwise, a deprecation notice is emitted. Note that lack of an explicit return declaration is also considered a signature mismatch, and thus results in the deprecation notice.

If the return type cannot be declared for an overriding method due to PHP cross-version compatibility concerns, a#[ReturnTypeWillChange]attribute can be added to silence the deprecation notice.

Ejemplo #2 The overriding method does not declare any return type

<?php
classMyDateTimeextendsDateTime
{
public function
modify(string $modifier) { returnfalse; }
}

// "Deprecated: Return type of MyDateTime::modify(string $modifier) should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" as of PHP 8.1.0
?>

Ejemplo #3 The overriding method declares a wrong return type

<?php
classMyDateTimeextendsDateTime
{
public function
modify(string $modifier): ?DateTime{ returnnull; }
}

// "Deprecated: Return type of MyDateTime::modify(string $modifier): ?DateTime should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" as of PHP 8.1.0
?>

Ejemplo #4 The overriding method declares a wrong return type without a deprecation notice

<?php
classMyDateTimeextendsDateTime
{
/**
* @return DateTime|false
*/
#[ReturnTypeWillChange]
public functionmodify(string $modifier) { returnfalse; }
}

// No notice is triggered
?>


Operador de Resolución de Ámbito (::)

El Operador de Resolución de Ámbito (también denominado Paamayim Nekudotayim) o en términos simples, el doble dos-puntos, es un token que permite acceder a elementosestáticos,constantes, y sobrescribir propiedades o métodos de una clase.

Cuando se hace referencia a estos items desde el exterior de la definición de la clase, se utiliza el nombre de la clase.

A partir de PHP 5.3.0, es posible hacer referencia a una clase usando una variable. El valor de la variable no puede ser una palabra clave (por ej.,self,parentystatic).

Paamayim Nekudotayim podría, en un principio, parecer una extraña elección para bautizar a un doble dos-puntos. Sin embargo, mientras se escribía el Zend Engine 0.5 (que utilizó PHP 3), asi es como el equipo Zend decidió bautizarlo. En realidad, significa doble dos-puntos - en Hebreo!

Ejemplo #1 :: desde el exterior de la definición de la clase

<?php
classMyClass{
const
CONST_VALUE='Un valor constante';
}

$classname='MyClass';
echo
$classname::CONST_VALUE;// A partir de PHP 5.3.0

echoMyClass::CONST_VALUE;
?>

Las tres palabras claves especialesself,parentystaticson utilizadas para acceder a propiedades y métodos desde el interior de la definición de la clase.

Ejemplo #2 :: desde el interior de la definición de la clase

<?php
classOtherClassextendsMyClass
{
public static
$my_static='variable estática';

public static function
doubleColon() {
echo
parent::CONST_VALUE."\n";
echo
self::$my_static."\n";
}
}

$classname='OtherClass';
$classname::doubleColon();// A partir de PHP 5.3.0

OtherClass::doubleColon();
?>

Cuando una clase extendida sobrescribe la definición parent de un método, PHP no invocará al método parent. Depende de la clase extendida el hecho de llamar o no al método parent. Esto también se aplica a definiciones de métodosConstructores y Destructores,Sobrecarga, yMágicos.

Ejemplo #3 Invocando a un método parent

<?php
classMyClass
{
protected function
myFunc() {
echo
"MyClass::myFunc()\n";
}
}

class
OtherClassextendsMyClass
{
// Sobrescritura de definición parent
public functionmyFunc()
{
// Pero todavía se puede llamar a la función parent
parent::myFunc();
echo
"OtherClass::myFunc()\n";
}
}

$class= newOtherClass();
$class->myFunc();
?>

Véase tambiénalgunos ejemplos de trucos de llamadas estáticas.



La palabra reservada 'static'

Sugerencia

Esta página describe el uso de la palabra reservadastaticpara definir métodos y propiedades estáticos.statictambién se puede usar paradefinir variables estáticasy paraenlaces estáticos en tiempo de ejecución. Por favor, consulte estas páginas para más información sobre estos significados destatic.

Declarar propiedades o métodos de clases como estáticos los hacen accesibles sin la necesidad de instanciar la clase. Una propiedad declarada como static no puede ser accedida con un objeto de clase instanciado (aunque un método estático sí lo puede hacer).

Por motivos de compatibilidad con PHP 4, si no se utiliza ninguna declaración devisibilidad, se tratará a las propiedades o métodos como si hubiesen sido definidos comopublic.

Métodos estáticos

Debido a que los métodos estáticos se pueden invocar sin tener creada una instancia del objeto, la seudovariable$thisno está disponible dentro de los métodos declarados como estáticos.

Precaución

En PHP 5, llamar a métodos no estáticos de forma estática genera una advertencia de nivelE_STRICT.

Advertencia

En PHP 7, llamar a métodos no estáticos de forma estática está obsoleto y generará una advertenciaE_DEPRECATED. El soporte para las llamadas a métodos no estáticos de forma estática podría ser eliminado en el futuro.

Ejemplo #1 Ejemplo de método estático

<?php
classFoo{
public static function
unMetodoEstatico() {
// ...
}
}

Foo::unMetodoEstatico();
$nombre_clase='Foo';
$nombre_clase::unMetodoEstatico();// A partir de PHP 5.3.0
?>

Propiedades estáticas

No se puede acceder a las propiedades estáticas a través del objeto utilizando el operador flecha (->).

Como cualquier otra variable estática de PHP, las propiedades estáticas sólo pueden ser inicializadas utilizando un string literal o una constante; las expresiones no están permitidas. Por tanto, se puede inicializar una propiedad estática con enteros o arrays (por ejemplo), pero no se puede hacer con otra variable, con el valor de devolución de una función, o con un objeto.

A partir de PHP 5.3.0, es posible hacer referencia a una clase usando una variable. El valor de la variable no puede ser una palabra reservada (p.ej.,self,parentystatic).

Ejemplo #2 Ejemplo de propiedad estática

<?php
classFoo
{
public static
$mi_static='foo';

public function
valorStatic() {
return
self::$mi_static;
}
}

class
BarextendsFoo
{
public function
fooStatic() {
return
parent::$mi_static;
}
}


print
Foo::$mi_static."\n";

$foo= newFoo();
print
$foo->valorStatic() ."\n";
print
$foo->mi_static."\n";// "Propiedad" mi_static no definida

print$foo::$mi_static."\n";
$nombreClase='Foo';
print
$nombreClase::$mi_static."\n";// A partir de PHP 5.3.0

printBar::$mi_static."\n";
$bar= newBar();
print
$bar->fooStatic() ."\n";
?>


Abstracción de clases

PHP 5 introduce clases y métodos abstractos. Las clases definidas como abstractas no se pueden instanciar y cualquier clase que contiene al menos un método abstracto debe ser definida como tal. Los métodos definidos como abstractos simplemente declaran la firma del método, pero no pueden definir la implementación.

Cuando se hereda de una clase abstracta, todos los métodos definidos como abstractos en la declaración de la clase madre deben ser definidos en la clase hija; además, estos métodos deben ser definidos con la misma (o con una menos restrictiva)visibilidad. Por ejemplo, si el método abstracto está definido como protegido, la implementación de la función debe ser definida como protegida o pública, pero nunca como privada. Por otra parte, las firmas de los métodos tienen que coincidir, es decir, la declaración de tipos y el número de argumentos requeridos deben ser los mismos. Por ejemplo, si la clase derivada define un argumento opcional y la firma del método abstracto no lo hace, no habría conflicto con la firma. Esto también se aplica a los constructores a partir de PHP 5.4. Antes de PHP 5.4, las firmas del constructor podían ser diferentes.

Ejemplo #1 Ejemplo de clase abstracta

<?php
abstract classClaseAbstracta
{
// Forzar la extensión de clase para definir este método
abstract protected functiongetValor();
abstract protected function
valorPrefijo($prefijo);

// Método común
public functionimprimir() {
print
$this->getValor() ."\n";
}
}

class
ClaseConcreta1extendsClaseAbstracta
{
protected function
getValor() {
return
"ClaseConcreta1";
}

public function
valorPrefijo($prefijo) {
return
"{$prefijo}ClaseConcreta1";
}
}

class
ClaseConcreta2extendsClaseAbstracta
{
public function
getValor() {
return
"ClaseConcreta2";
}

public function
valorPrefijo($prefijo) {
return
"{$prefijo}ClaseConcreta2";
}
}

$clase1= newClaseConcreta1;
$clase1->imprimir();
echo
$clase1->valorPrefijo('FOO_') ."\n";

$clase2= newClaseConcreta2;
$clase2->imprimir();
echo
$clase2->valorPrefijo('FOO_') ."\n";
?>

El resultado del ejemplo sería:

ClaseConcreta1
FOO_ClaseConcreta1
ClaseConcreta2
FOO_ClaseConcreta2

Ejemplo #2 Ejemplo de clase abstracta

<?php
abstract classClaseAbstracta
{
// El método abstracto sólo necesita definir los argumentos requeridos
abstract protected functionnombrePrefijo($nombre);

}

class
ClaseConcretaextendsClaseAbstracta
{

// La clase derivada puede definir parámetros opcionales que no estén en la estructura del prototipo
public functionnombrePrefijo($nombre,$separador=".") {
if (
$nombre=="Pacman") {
$prefijo="Mr";
} elseif (
$nombre=="Pacwoman") {
$prefijo="Mrs";
} else {
$prefijo="";
}
return
"{$prefijo}{$separador}{$nombre}";
}
}

$clase= newClaseConcreta;
echo
$clase->nombrePrefijo("Pacman"),"\n";
echo
$clase->nombrePrefijo("Pacwoman"),"\n";
?>

El resultado del ejemplo sería:

Mr. Pacman
Mrs. Pacwoman

El código antiguo que no tenga clases o funciones definidas por el usuario llamadas 'abstract' deberían ejecutarse sin modificaciones.



Interfaces de objetos

Las interfaces de objetos permiten crear código con el cual especificar qué métodos deben ser implementados por una clase, sin tener que definir cómo estos métodos son manipulados.

Las interfaces se definen de la misma manera que una clase, aunque reemplazando la palabra reservadaclasspor la palabra reservadainterfacey sin que ninguno de sus métodos tenga su contenido definido.

Todos los métodos declarados en una interfaz deben ser públicos, ya que ésta es la naturaleza de una interfaz.

implements

Para implementar una interfaz, se utiliza el operadorimplements. Todos los métodos en una interfaz deben ser implementados dentro de la clase; el no cumplir con esta regla resultará en un error fatal. Las clases pueden implementar más de una interfaz si se deseara, separándolas cada una por una coma.

Nota:

Antes de PHP 5.3.9, una clase no puede implementar dos interfaces que especifiquen un método con el mismo nombre, ya que podría causar ambigüedad. Las versiones más recientes de PHP permiten esto siempre y cuando los métodos duplicados tengan la misma firma.

Nota:

Las interfaces se pueden extender al igual que las clases utilizando el operadorextends.

Nota:

La clase que implemente una interfaz debe utilizar exactamente las mismas estructuras de métodos que fueron definidos en la interfaz. De no cumplir con esta regla, se generará un error fatal.

Constantes

Es posible tener constantes dentro de las interfaces. Las constantes de interfaces funcionan como lasconstantes de clasesexcepto porque no pueden ser sobrescritas por una clase/interfaz que las herede.

Ejemplos

Ejemplo #1 Ejemplo de interfaz

<?php

// Declarar la interfaz 'iTemplate'
interfaceiTemplate
{
public function
setVariable($name,$var);
public function
getHtml($template);
}

// Implementar la interfaz
// Ésto funcionará
classTemplateimplementsiTemplate
{
private
$vars= array();

public function
setVariable($name,$var)
{
$this->vars[$name] =$var;
}

public function
getHtml($template)
{
foreach(
$this->varsas$name=>$value) {
$template=str_replace('{'.$name.'}',$value,$template);
}

return
$template;
}
}
// Ésto no funcionará
// Error fatal: La Clase BadTemplate contiene un método abstracto
// y por lo tanto debe declararse como abstracta (iTemplate::getHtml)
classBadTemplateimplementsiTemplate
{
private
$vars= array();

public function
setVariable($name,$var)
{
$this->vars[$name] =$var;
}
}
?>

Ejemplo #2 Interfaces extensibles

<?php
interfacea
{
public function
foo();
}

interface
bextendsa
{
public function
baz(Baz $baz);
}

// Ésto sí funcionará
classcimplementsb
{
public function
foo()
{
}

public function
baz(Baz $baz)
{
}
}

// Ésto no funcionará y resultará en un error fatal
classdimplementsb
{
public function
foo()
{
}

public function
baz(Foo $foo)
{
}
}
?>

Ejemplo #3 Herencia múltiple de interfaces

<?php
interfacea
{
public function
foo();
}

interface
b
{
public function
bar();
}

interface
cextendsa,b
{
public function
baz();
}

class
dimplementsc
{
public function
foo()
{
}

public function
bar()
{
}

public function
baz()
{
}
}
?>

Ejemplo #4 Interfaces con constantes

<?php
interfacea
{
const
b='Interface constant';
}

// Imprime: Interface constant
echoa::b;


// Sin embargo ésto no funcionará ya que no está permitido
// sobrescribir constantes
classbimplementsa
{
const
b='Class constant';
}
?>

Una interfaz, junto con la determinación de tipos, proveen una buena forma de asegurarse que determinado objeto contiene métodos particulares. Vea el operadorinstanceofy ladeclaración de tipos.



Rasgos (Traits)

Desde su versión 5.4.0, PHP implementa una metodología de reutilización de código llamada Traits.

Los rasgos («traits» en inglés) son un mecanismo de reutilización de código en lenguajes de herencia simple, como PHP. El objetivo de un rasgo es el de reducir las limitaciones propias de la herencia simple permitiendo que los desarrolladores reutilicen a voluntad conjuntos de métodos sobre varias clases independientes y pertenecientes a clases jerárquicas distintas. La semántica a la hora combinar Traits y clases se define de tal manera que reduzca su complejidad y se eviten los problemas típicos asociados a la herencia múltiple y a los Mixins.

Un Trait es similar a una clase, pero con el único objetivo de agrupar funcionalidades muy específicas y de una manera coherente. No se puede instanciar directamente un Trait. Es por tanto un añadido a la herencia tradicional, y habilita la composición horizontal de comportamientos; es decir, permite combinar miembros de clases sin tener que usar herencia.

Ejemplo #1 Ejemplo de rasgo

<?php
traitezcReflectionReturnInfo{
function
getReturnType() {/*1*/}
function
getReturnDescription() {/*2*/}
}

class
ezcReflectionMethodextendsReflectionMethod{
use
ezcReflectionReturnInfo;
/* ... */
}

class
ezcReflectionFunctionextendsReflectionFunction{
use
ezcReflectionReturnInfo;
/* ... */
}
?>

Precedencia

Los miembros heredados de una clase base se sobrescriben cuando se inserta otro miembro homónimo desde un Trait. De acuerdo con el orden de precedencia, los miembros de la clase actual sobrescriben los métodos del Trait, que a su vez sobrescribe los métodos heredados.

Ejemplo #2 Ejemplo de Orden de Precedencia

Se sobrescribe un miembro de la clase base con el método insertado en MiHolaMundo a partir del Trait DecirMundo. El comportamiento es el mismo para los métodos definidos en la clase MiHolaMundo. Según el orden de precedencia los métodos de la clase actual sobrescriben los métodos del Trait, a la vez que el Trait sobrescribe los métodos de la clase base.

<?php
classBase{
public function
decirHola() {
echo
'¡Hola ';
}
}

trait
DecirMundo{
public function
decirHola() {
parent::decirHola();
echo
'Mundo!';
}
}

class
MiHolaMundoextendsBase{
use
DecirMundo;
}

$o= newMiHolaMundo();
$o->decirHola();
?>

El resultado del ejemplo sería:

¡Hola Mundo!

Ejemplo #3 Ejemplo de Orden de Precedencia #2

<?php
traitHolaMundo{
public function
decirHola() {
echo
'¡Hola Mundo!';
}
}

class
ElMundoNoEsSuficiente{
use
HolaMundo;
public function
decirHola() {
echo
'¡Hola Universo!';
}
}

$o= newElMundoNoEsSuficiente();
$o->decirHola();
?>

El resultado del ejemplo sería:

¡Hola Universo!

Multiples Traits

Se pueden insertar múltiples Traits en una clase, mediante una lista separada por comas en la sentencia use.

Ejemplo #4 Uso de varios rasgos

<?php
traitHola{
public function
decirHola() {
echo
'Hola ';
}
}

trait
Mundo{
public function
decirMundo() {
echo
'Mundo';
}
}

class
MiHolaMundo{
use
Hola,Mundo;
public function
decirAdmiración() {
echo
'!';
}
}

$o= newMiHolaMundo();
$o->decirHola();
$o->decirMundo();
$o->decirAdmiración();
?>

El resultado del ejemplo sería:

Hola Mundo!

Resolución de Conflictos

Si dos Traits insertan un método con el mismo nombre, se produce un error fatal, siempre y cuando no se haya resuelto explicitamente el conflicto.

Para resolver los conflictos de nombres entre Traits en una misma clase, se debe usar el operadorinsteadofpara elegir unívocamente uno de los métodos conflictivos.

Como esto solamente permite excluir métodos, se puede utilizar el operadoraspara añadir un alias a uno de los métodos. Observe que el operadorasno renombra el método ni afecta a cualquier otro método.

Ejemplo #5 Resolución de Conflictos

En este ejemplo, Talker utiliza los traits A y B. Como A y B tienen métodos conflictos, se define el uso de la variante de smallTalk del trait B, y la variante de bigTalk del trait A.

Aliased_Talker hace uso del operadoraspara poder usar la implementación de bigTalk de B, bajo el alias adicionaltalk.

<?php
traitA{
public function
smallTalk() {
echo
'a';
}
public function
bigTalk() {
echo
'A';
}
}

trait
B{
public function
smallTalk() {
echo
'b';
}
public function
bigTalk() {
echo
'B';
}
}

class
Talker{
use
A,B{
B::smallTalkinsteadofA;
A::bigTalkinsteadofB;
}
}

class
Aliased_Talker{
use
A,B{
B::smallTalkinsteadofA;
A::bigTalkinsteadofB;
B::bigTalkastalk;
}
}
?>

Nota:

Antes de PHP 7.0, definir una propiedad en una clase con el mismo nombre que en un rasgo lanzaba unE_STRICTsi la definición de la clase era compatible (misma visivilidad y mismo valor inicial).

Modificando la Visibilidad de los Métodos

Al usar el operadoras, se puede también ajustar la visibilidad del método en la clase exhibida.

Ejemplo #6 Modificar la Visibilidad de un Método

<?php
traitHolaMundo{
public function
decirHola() {
echo
'Hola Mundo!';
}
}

// Cambiamos visibilidad de decirHola
classMiClase1{
use
HolaMundo{decirHolaas protected; }
}

// Método alias con visibilidad cambiada
// La visibilidad de decirHola no cambia
classMiClase2{
use
HolaMundo{decirHolaas privatemiPrivadoHola; }
}
?>

Traits Compuestos de Traits

Al igual que las clases, los Traits también pueden hacer uso de otros Traits. Al usar uno o más traits en la definición de un trait, éste puede componerse parcial o completamente de miembros definidos en esos otros traits.

Ejemplo #7 Traits compuestos de traits

<?php
traitHola{
public function
decirHola() {
echo
'Hola ';
}
}

trait
Mundo{
public function
decirMundo() {
echo
'Mundo!';
}
}

trait
HolaMundo{
use
Hola,Mundo;
}

class
MiHolaMundo{
use
HolaMundo;
}

$o= newMiHolaMundo();
$o->decirHola();
$o->decirMundo();
?>

El resultado del ejemplo sería:

Hola Mundo!

Miembros Abstractos de Traits

Los traits soportan el uso de métodos abstractos para imponer requisitos a la clase a la que se exhiban.

Precaución

Una clase concreta cumple este requisito definiendo un método concreto con el mismo nombre; su firma puede ser diferente.

Ejemplo #8 Expresar Resquisitos con Métodos Abstractos

<?php
traitHola{
public function
decirHolaMundo() {
echo
'Hola'.$this->obtenerMundo();
}
abstract public function
obtenerMundo();
}

class
MiHolaMundo{
private
$mundo;
use
Hola;
public function
obtenerMundo() {
return
$this->mundo;
}
public function
asignarMundo($val) {
$this->mundo=$val;
}
}
?>

Miembros Estáticos en Traits

Los trait pueden definir miembros y métodos estáticos.

Ejemplo #9 Variables estáticas

<?php
traitContador{
public function
inc() {
static
$c=0;
$c=$c+1;
echo
"$c\n";
}
}

class
C1{
use
Contador;
}

class
C2{
use
Contador;
}

$o= newC1();$o->inc();// echo 1
$p= newC2();$p->inc();// echo 1
?>

Ejemplo #10 Métodos Estáticos

<?php
traitEjemploEstatico{
public static function
hacerAlgo() {
return
'Hacer algo';
}
}

class
Ejemplo{
use
EjemploEstatico;
}

Ejemplo::hacerAlgo();
?>

Propiedades

Los traits también pueden definir propiedades.

Ejemplo #11 Definir Propiedades

<?php
traitPropiedadesTrait{
public
$x=1;
}

class
EjemploPropiedades{
use
PropiedadesTrait;
}

$ejemplo= newEjemploPropiedades;
$ejemplo->x;
?>

Si un trait define una propiedad, una clase no puede definir una propiedad con el mismo nombre, a menos que sea compatible (misma visibilidad y mismo valor inicial), si no, se emitirá un error fatal. Antes de PHP 7.0, definir una propiedad en una clase con la misma visibilidad y el mismo valor inicial que en el rasgo, emitía un aviso E_STRICT.

Ejemplo #12 Resolución de Conflictos

<?php
traitPropiedadesTrait{
public
$misma=true;
public
$diferente=false;
}

class
EjemploPropiedades{
use
PropiedadesTrait;
public
$misma=true;// Permitido a partir de PHP 7.0.0; aviso E_STRICT anteriormente
public$diferente=true;// Error fatal
}
?>


Clases anónimas

En PHP 7 se ha añadido soporte para clases anónimas. Las clases anónimas son útiles cuando es necesario crear objetos sencillos y únicos.

<?php

// Código anterior a PHP 7
classLogger
{
public function
log($msg)
{
echo
$msg;
}
}

$util->setLogger(newLogger());

// Código de PHP 7+
$util->setLogger(new class {
public function
log($msg)
{
echo
$msg;
}
});

Pueden pasar argumentos a través de sus constructores, extender otras clases, implementar interfaces, y utilizar rasgos al igual que una clase normal:

<?php

classSomeClass{}
interface
SomeInterface{}
trait
SomeTrait{}

var_dump(new class(10) extendsSomeClassimplementsSomeInterface{
private
$num;

public function
__construct($num)
{
$this->num=$num;
}

use
SomeTrait;
});

El resultado del ejemplo sería:

object(class@anonymous)#1 (1) {
  ["Command line code0x104c5b612":"class@anonymous":private]=>
  int(10)
}

El anidamiento de una clase anónima dentro de otra clase no le proporciona acceso a ningún método o propiedad privados o protegidos de la clase externa. Para utilizar las propiedades o métodos protegidos de la clase externa, la clase anónima puede extender la clase externa. Para utilizar las propiedades privadas de la clase externa en la clase anónima, estos deben pasarse a su constructor:

<?php

classExterna
{
private
$prop=1;
protected
$prop2=2;

protected function
func1()
{
return
3;
}

public function
func2()
{
return new class(
$this->prop) extendsExterna{
private
$prop3;

public function
__construct($prop)
{
$this->prop3=$prop;
}

public function
func3()
{
return
$this->prop2+$this->prop3+$this->func1();
}
};
}
}

echo (new
Externa)->func2()->func3();

El resultado del ejemplo sería:

6

Todos los objetos creados por la misma declaración de clase anónima son instancias de esa misma clase.

<?php
functionclase_anónima()
{
return new class {};
}

if (
get_class(clase_anónima()) ===get_class(clase_anónima())) {
echo
'misma clase';
} else {
echo
'clase diferente';
}

El resultado del ejemplo sería:

misma clase

Nota:

Observe que el motor le asigna un nombre a las clases anónimas, como se demuestra en el siguiente ejemplo. Este nombre name ha de considerarse un detalle de implementación del cual no se debería depender.

<?php
echoget_class(new class {});

El resultado del ejemplo sería algo similar a:

class@anonymous/in/oNi1A0x7f8636ad2021



Sobrecarga

La sobrecarga en PHP ofrece los medios paracreardinámicamente propiedades y métodos. Estas entidades dinámicas se procesan por los métodos mágicos que se pueden establecer en una clase para diversas acciones.

Se invoca a los métodos de sobrecarga cuando se interactúa con propiedades o métodos que no se han declarado o que no sonvisiblesen el ámbito activo. A lo largo de esta sección usaremos los términospropiedades inaccesiblesymétodos inaccesiblespara referirnos a esta combinación de declaración y visibilidad.

Todos los métodos sobrecargados deben definirse comopublic.

Nota:

No se puede pasar ninguno de los parámetros de estos métodos mágicospor referencia.

Nota:

La interpretación de PHP deoverloadinges distinta de la mayoría de los lenguajes orientados a objetos. La sobrecarga tradicionalmente ofrece la capacidad de tener múltiples métodos con el mismo nombre, pero con un tipo o un número distinto de parámetros.

Historial de cambios

VersiónDescripción
5.3.0Se añadió__callStatic. Se añadieron advertencias para hacer cumplir la visibilidad pública e impedir la declaración static.
5.1.0Se añadieron__isset()y__unset(). Se añadió el soporte para__get()para la sobrecarga de propiedades privadas.
5.0.0Se añadió__get().

Sobrecarga de propiedades

public__set(string$name,mixed$value):void
public__get(string$name):mixed
public__isset(string$name):bool
public__unset(string$name):void

__set()se ejecuta al escribir datos sobre propiedades inaccesibles (protegidas o privadas) o inexistentes.

__get()se utiliza para consultar datos a partir de propiedades inaccesibles (protegidas o privadas) o inexistentes.

__isset()se lanza al llamar aisset()o aempty()sobre propiedades inaccesibles (protegidas o privadas) o inexistentes.

__unset()se invoca cuando se usaunset()sobre propiedades inaccesibles (protegidas o privadas) o inexistentes.

El parámetro$namees el nombre de la propiedad con la que se está interactuando. En el método__set()el parámetro$valueespecifica el valor que se debe asignar a la propiedad$name.

La sobrecarga de propiedades sólo funciona en contextos de objetos. Estos métodos mágicos no se lanzarán en contextos estáticos. Por esa razón, no se deben declarar comoestáticos. Desde PHP 5.3.0, se emite un aviso si alguno de los métodos de sobrecarga es declarado comostatic.

Nota:

Debido a la forma en que PHP procesa el operador de asignación, el valor que devuelve__set()se ignora. Del mismo modo, nunca se llama a__get()al encadenar asignaciones como esta:

 $a = $obj->b = 8; 

Ejemplo #1 Sobrecarga de propiedades mediante los métodos__get(),__set(),__isset()y__unset()

<?php
classPropertyTest
{
/** Localización de los datos sobrecargados. */
private$data= array();

/** La sobrecarga no se usa en propiedades declaradas. */
public$declared=1;

/** La sobre carga sólo funciona aquí al acceder desde fuera de la clase. */
private$hidden=2;

public function
__set($name,$value)
{
echo
"Estableciendo '$name' a '$value'\n";
$this->data[$name] =$value;
}

public function
__get($name)
{
echo
"Consultando '$name'\n";
if (
array_key_exists($name,$this->data)) {
return
$this->data[$name];
}

$trace=debug_backtrace();
trigger_error(
'Propiedad indefinida mediante __get(): '.$name.
' en '.$trace[0]['file'] .
' en la línea '.$trace[0]['line'],
E_USER_NOTICE);
return
null;
}

/** Desde PHP 5.1.0 */
public function__isset($name)
{
echo
"¿Está definido '$name'?\n";
return isset(
$this->data[$name]);
}

/** Desde PHP 5.1.0 */
public function__unset($name)
{
echo
"Eliminando '$name'\n";
unset(
$this->data[$name]);
}

/** No es un método mágico, esta aquí para completar el ejemplo. */
public functiongetHidden()
{
return
$this->hidden;
}
}


echo
"<pre>\n";

$obj= newPropertyTest;

$obj->a=1;
echo
$obj->a."\n\n";

var_dump(isset($obj->a));
unset(
$obj->a);
var_dump(isset($obj->a));
echo
"\n";

echo
$obj->declared."\n\n";

echo
"Vamos a probar con la propiedad privada que se llama 'hidden':\n";
echo
"Las propiedades privadas pueden consultarse en la clase, por lo que no se usa __get()...\n";
echo
$obj->getHidden() ."\n";
echo
"Las propiedades privadas no son visibles fuera de la clase, por lo que se usa __get()...\n";
echo
$obj->hidden."\n";
?>

El resultado del ejemplo sería:

Estableciendo 'a' a '1'
Consultando 'a'
1

¿Está definido 'a'?
bool(true)
Eliminando 'a'
¿Está definido 'a'?
bool(false)

1

Vamos a probar con la propiedad privada que se llama 'hidden':
Las propiedades privadas pueden consultarse en la clase, por lo que no se usa __get()...
2
Las propiedades privadas no son visibles fuera de la clase, por lo que se usa __get()...
Consultando 'hidden'


Notice:  Propiedad indefinida mediante __get(): hidden en <file> en la línea 69 in <file>en la línea 28

Sobrecarga de métodos

public__call(string$name,array$arguments):mixed
public static__callStatic(string$name,array$arguments):mixed

__call()es lanzado al invocar un método inaccesible en un contexto de objeto.

__callStatic()es lanzado al invocar un método inaccesible en un contexto estático.

El parámetro$namecorresponde al nombre del método al que se está llamando. El parámetro$argumentses un array enumerado que contiene los parámetros que se han pasado al método$name.

Ejemplo #2 Sobrecarga de métodos mediante los métodos__call()and__callStatic()

<?php
classMethodTest
{
public function
__call($name,$arguments)
{
// Nota: el valor $name es sensible a mayúsculas.
echo"Llamando al método de objeto '$name' "
.implode(', ',$arguments)."\n";
}

/** Desde PHP 5.3.0 */
public static function__callStatic($name,$arguments)
{
// Nota: el valor $name es sensible a mayúsculas.
echo"Llamando al método estático '$name' "
.implode(', ',$arguments)."\n";
}
}

$obj= newMethodTest;
$obj->runTest('en contexto de objeto');

MethodTest::runTest('en contexto estático');// Desde PHP 5.3.0
?>

El resultado del ejemplo sería:

Llamando al método de objeto 'runTest' en contexto de objeto
Llamando al método estático 'runTest' en contexto estático


Iteración de objetos

PHP 5 ofrece una manera para definir objetos, por lo que es posible recorrer una lista de elementos con, por ejemplo, una sentenciaforeach. Por defecto, se utilizarán todas las propiedadesvisiblespara la iteración.

Ejemplo #1 Iteración simple de un objeto

<?php
classMiClase
{
public
$var1='valor 1';
public
$var2='valor 2';
public
$var3='valor 3';

protected
$protected='variable protegida';
private
$private='variable privada';

function
iterateVisible() {
echo
"MiClase::iterateVisible:\n";
foreach (
$thisas$clave=>$valor) {
print
"$clave=>$valor\n";
}
}
}

$clase= newMiClase();

foreach(
$claseas$clave=>$valor) {
print
"$clave=>$valor\n";
}
echo
"\n";


$clase->iterateVisible();

?>

El resultado del ejemplo sería:

var1 => valor 1
var2 => valor 2
var3 => valor 3

MiClase::iterateVisible:
var1 => valor 1
var2 => valor 2
var3 => valor 3
protected => variable protegida
private => variable privada

Como se muestra en la salida,foreachrecorre todas las propiedadesvisiblesa las que se pueden acceder.

Para dar un paso más, se puede implementar lainterfazIterator. Esto permite al objeto decidir cómo será iterado y qué valores estarán disponibles en cada iteración.

Ejemplo #2 Iteración de un objeto implementando Iterator

<?php
classMiIteradorimplementsIterator
{
private
$var= array();

public function
__construct($array)
{
if (
is_array($array)) {
$this->var=$array;
}
}

public function
rewind()
{
echo
"rebobinando\n";
reset($this->var);
}

public function
current()
{
$var=current($this->var);
echo
"actual:$var\n";
return
$var;
}

public function
key()
{
$var=key($this->var);
echo
"clave:$var\n";
return
$var;
}

public function
next()
{
$var=next($this->var);
echo
"siguiente:$var\n";
return
$var;
}

public function
valid()
{
$clave=key($this->var);
$var= ($clave!==NULL&&$clave!==FALSE);
echo
"válido:$var\n";
return
$var;
}

}

$valores= array(1,2,3);
$it= newMiIterador($valores);

foreach (
$itas$a=>$b) {
print
"$a:$b\n";
}
?>

El resultado del ejemplo sería:

rebobinando
válido: 1
actual: 1
clave: 0
0: 1
siguiente: 2
válido: 1
actual: 2
clave: 1
1: 2
siguiente: 3
válido: 1
actual: 3
clave: 2
2: 3
siguiente:
válido:

LainterfazIteratorAggregatese puede usar como alternativa para implementar todos los métodos deIterator.IteratorAggregatesolamente requiere la implementación de un único método,IteratorAggregate::getIterator(), el cual debería devolver una instancia de una clase que implementeIterator.

Ejemplo #3 Iteración de un objeto implementando IteratorAggregate

<?php
classMiColecciónimplementsIteratorAggregate
{
private
$items= array();
private
$cuenta=0;

// Se requiere la definición de la interfaz IteratorAggregate
public functiongetIterator() {
return new
MiIterador($this->items);
}

public function
add($valor) {
$this->items[$this->cuenta++] =$valor;
}
}

$colección= newMiColección();
$colección->add('valor 1');
$colección->add('valor 2');
$colección->add('valor 3');

foreach (
$colecciónas$clave=>$val) {
echo
"clave/valor: [$clave->$val]\n\n";
}
?>

El resultado del ejemplo sería:

rebobinando
actual: valor 1
válido: 1
actual: valor 1
clave: 0
clave/valor: [0 -> valor 1]

siguiente: valor 2
actual: valor 2
válido: 1
actual: valor 2
clave: 1
clave/valor: [1 -> valor 2]

siguiente: valor 3
actual: valor 3
válido: 1
actual: valor 3
clave: 2
clave/valor: [2 -> valor 3]

siguiente:
actual:
válido:

Nota:

Para más ejemplos de iteradores, véase laextensión SPL.

Nota:

Los usuarios de PHP 5.5 y posteriores pueden investigar losgeneradores, los cuales posibilitan una forma alternativa de definir iteradores.



Métodos mágicos

Los métodos mágicos son métodos especiales que sobreescriben acciones por defecto cuando se realizan ciertas acciones sobre un objeto.

Precaución

Todos los nombres de los métodos que comienzan con__son reservados por PHP. Por lo tanto, se recomienda que no utilice los nombres de métodos a menos que se sobreescriba el comportamiento de PHP.

Los siguientes nombres de métodos se consideran mágicos:__construct(),__destruct(),__call(),__callStatic(),__get(),__set(),__isset(),__unset(),__sleep(),__wakeup(),__serialize(),__unserialize(),__toString(),__invoke(),__set_state(),__clone(), and__debugInfo().

Advertencia

Todos los métodos mágicos, a excepción de__construct(),__destruct(), y__clone(),deben serdeclarados comopúblico, en caso contrario se emite unE_WARNING. Antes de PHP 8.0.0, no se emitía ningún diagnóstico para los métodos mágicos__sleep(),__wakeup(),__serialize(),__unserialize(), y__set_state().

Advertencia

Si se utilizan tipo de declaraciones usados en la definición de un método mágico, deben ser idénticas a la firma descrita en este documento. De lo contrario, se emite un error fatal. Antes de PHP 8.0.0, no se emitía ningún diagnóstico. Sin embargo,__construct()y__destruct()no debe declarar un tipo de retorno; de lo contrario se emite un error fatal.

__sleep()y__wakeup()

public__sleep():array
public__wakeup():void

serialize()comprueba si la clase tiene un método con el nombre mágico__sleep(). Si es así, el método se ejecuta antes de cualquier serialización. Se puede limpiar el objeto y se supone que devuelve un array con los nombres de todas las variables de el objeto que se va a serializar. Si el método no devuelve nada, entoncesnulles serializado y un errorE_NOTICEes emitido.

Nota:

No es posible para__sleep()devolver nombres de propiedades privadas en las clases padres. Hacer esto resultaría un nivel de errorE_NOTICE. En su lugar, puede utilizar la interfazSerializable.

El uso para el que está destinado__sleep()consiste en confirmar datos pendientes o realizar tareas similares de limpieza. Además, el método es útil si tiene objetos muy grandes que no necesitan guardarse por completo.

Por el contrario,unserialize()comprueba la presencia de un método con el nombre mágico__wakeup(). Si está presente, este método puede reconstruir cualquier recurso que el objeto pueda tener.

El uso para el que está destinado__wakeup()es restablecer las conexiones de base de datos que se puedan haber perdido durante la serialización y realizar otras tareas de reinicialización.

Ejemplo #1 Sleep y wakeup

<?php
classConnection
{
protected
$link;
private
$dsn,$username,$password;

public function
__construct($dsn,$username,$password)
{
$this->dsn=$dsn;
$this->username=$username;
$this->password=$password;
$this->connect();
}

private function
connect()
{
$this->link= newPDO($this->dsn,$this->username,$this->password);
}

public function
__sleep()
{
return array(
'dsn','username','password');
}

public function
__wakeup()
{
$this->connect();
}
}
?>

__serialize()y__unserialize()

public__serialize():array
public__unserialize(array$data):void

serialize()comprueba si la clase tiene una función mágica con el nombre__serialize(). Si es así, esa función se ejecuta antes de cualquier serialización. Debe construir y devolver un array asociativo de pares clave/valor que representen la forma serializada del objeto. Si no se devuelve ningún array, se lanzará una claseTypeError.

Nota:

Si tanto__serialize()y__sleep()están definidos en el mismo objeto, sólo se llamará a__serialize().__sleep()será ignorado. Si el objeto implementa la interfazSerializableel métodoserialize()de la interfaz será ignorado y se utilizará__serialize()en su lugar.

El uso previsto de__serialize()es definir una representación arbitraria del objeto que sea fácil de serializar. Los elementos de la matriz pueden corresponder a propiedades del objeto, pero no es necesario.

Por el contrario,unserialize()comprueba la presencia de una función con el nombre mágico__unserialize(). Si está presente, a esta función se le pasará el array restaurado que fue devuelto por__serialize(). Entonces puede restaurar las propiedades del objeto desde ese array según sea apropiado.

Nota:

Si tanto__unserialize()y__wakeup()son definidos en el mismo objeto, sólo se llamará a__unserialize().__wakeup()será ignorado.

Nota:

Esta función está disponible a partir de PHP 7.4.0.

Ejemplo #2 Serialize y unserialize

<?php
classConnection
{
protected
$link;
private
$dsn,$username,$password;

public function
__construct($dsn,$username,$password)
{
$this->dsn=$dsn;
$this->username=$username;
$this->password=$password;
$this->connect();
}

private function
connect()
{
$this->link= newPDO($this->dsn,$this->username,$this->password);
}

public function
__serialize(): array
{
return [
'dsn'=>$this->dsn,
'user'=>$this->username,
'pass'=>$this->password,
];
}

public function
__unserialize(array$data):void
{
$this->dsn=$data['dsn'];
$this->username=$data['user'];
$this->password=$data['pass'];

$this->connect();
}
}
?>

__toString()

public__toString():string

El método__toString()permite a una clase decidir cómo comportarse cuando se le trata como un string. Por ejemplo, lo queecho $obj;mostraría. Este método debe devolver un string, si no se emitirá un nivel de error fatalE_RECOVERABLE_ERROR.

Advertencia

As of PHP 8.0.0, the return value follows standard PHP type semantics, meaning it will be coerced into astringif possible and ifstrict typingis disabled.

As of PHP 8.0.0, any class that contains a__toString()method will also implicitly implement theStringableinterface, and will thus pass type checks for that interface. Explicitly implementing the interface anyway is recommended.

In PHP 7.4, the returned valuemustbe astring, otherwise anErroris thrown.

Prior to PHP 7.4.0, the returned valuemustbe astring, otherwise a fatalE_RECOVERABLE_ERRORis emitted.

Advertencia

No se puede lanzar una excepción desde dentro un método__toString(). El método antes de PHP 7.4.0. Si lo hace, se producirá un error fatal.

Ejemplo #3 Ejemplo simple

<?php
// Declarar una clase simple
classTestClass
{
public
$foo;

public function
__construct($foo)
{
$this->foo=$foo;
}

public function
__toString()
{
return
$this->foo;
}
}

$class= newTestClass('Hola Mundo');
echo
$class;
?>

El resultado del ejemplo sería:

Hola Mundo

Antes de PHP 5.2.0 el método__toString()se llama sólo cuando se combina directamente conechooprint. Desde PHP 5.2.0, se le llama en cualquier contexto de string (e.j. enprintf()con el modificador%s) pero no en el contexto de otros tipos (e.j. con el modificador%d). Desde PHP 5.2.0, la conversión de los objetos sin el método__toString()a string podría causarE_RECOVERABLE_ERROR.

__invoke()

__invoke($...= ?):mixed

El método__invoke()es llamado cuando un script intenta llamar a un objeto como si fuera una función.

Nota:

Esta característica está disponible desde PHP 5.3.0.

Ejemplo #4 Uso de__invoke()

<?php
classCallableClass
{
public function
__invoke($x)
{
var_dump($x);
}
}
$obj= newCallableClass;
$obj(5);
var_dump(is_callable($obj));
?>

El resultado del ejemplo sería:

int(5)
bool(true)

__set_state()

static__set_state(array$properties):object

Este métodostatices llamado para las clases exportadas porvar_export().

El único parámetro de este método es un array que contiene las propiedades exportadas en la forma['property' => value, ...].

Ejemplo #5 Uso de__set_state()

<?php

classA
{
public
$var1;
public
$var2;

public static function
__set_state($an_array)
{
$obj= newA;
$obj->var1=$an_array['var1'];
$obj->var2=$an_array['var2'];
return
$obj;
}
}

$a= newA;
$a->var1=5;
$a->var2='foo';

$b=var_export($a,true);
var_dump($b);
eval(
'$c = '.$b.';');
var_dump($c);
?>

El resultado del ejemplo sería:

string(60) "A::__set_state(array(
   'var1' => 5,
   'var2' => 'foo',
))"
object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}

Nota:Al exportar un objeto,var_export()no comprueba si__set_state()está implementado por la clase del objeto, por lo que la reimportación de tales objetos dará lugar a una excepciónError, si __set_state() no está implementado. En particular, esto afecta a algunas clases internas.Es responsabilidad del programador verificar que solamente se vayan a reimportar los objetos cuya clase implemente __set_state().

__debugInfo()

__debugInfo():array

Este método es invocado porvar_dump()al volcar un objeto para obtener las propiedades que deberían mostrarse. Si el método no está definido sobre un objeto, se mostrarán todas las propiedades públicas protegidas y privadas.

Ejemplo #6 Utilizar__debugInfo()

<?php
classC{
private
$prop;

public function
__construct($val) {
$this->prop=$val;
}

public function
__debugInfo() {
return [
'propSquared'=>$this->prop**2,
];
}
}

var_dump(newC(42));
?>

El resultado del ejemplo sería:

object(C)#1 (1) {
  ["propSquared"]=>
  int(1764)
}


Palabra clave Final

PHP 5 introduce la nueva palabra clave final, que impide que las clases hijas sobrescriban un método, antecediendo su definición confinal. Si la propia clase se define como final, entonces no se podrá heredar de ella.

Ejemplo #1 Ejemplo de métodos Final

<?php
classBaseClass{
public function
test() {
echo
"llamada a BaseClass::test()\n";
}

final public function
moreTesting() {
echo
"llamada a BaseClass::moreTesting()\n";
}
}

class
ChildClassextendsBaseClass{
public function
moreTesting() {
echo
"llamada a ChildClass::moreTesting()\n";
}
}
// Devuelve un error Fatal: Cannot override final method BaseClass::moreTesting()
?>

Ejemplo #2 Ejemplo de clase Final

<?php
final classBaseClass{
public function
test() {
echo
"llamada a BaseClass::test()\n";
}

// Aquí no importa si definimos una función como final o no
final public functionmoreTesting() {
echo
"llamada a BaseClass::moreTesting()\n";
}
}

class
ChildClassextendsBaseClass{
}
// Devuelve un error Fatal: Class ChildClass may not inherit from final class (BaseClass)
?>

Nota:Las propiedades y las constantes no pueden declararse como final. Sólo pueden las clases y los métodos.



Clonación de Objetos

No siempre se desea crear una copia de un objeto replicando todas sus propiedades completamente. Un buen ejemplo que ilustra la necesidad de contar con un constructor de copias, sería si tuviéramos un objeto que represente una ventana en GTK y el objeto almacene los recursos de esta ventana GTK, de forma que cuando creas un duplicado el comportamiento esperado sería una nueva ventana con las mismas propiedades, y que el nuevo objeto referencie a los recursos de la nueva ventana. Otro ejemplo es si un objeto hace referencia a otro objeto necesario, de forma que cuando se realiza una réplica del objeto principal, se espera que se cree una nueva instancia de este otro objeto, de forma que la réplica tenga su propia copia.

Para crear una copia de un objeto se utiliza la palabra claveclone(que invoca, si fuera posible, al método__clone()del objeto). No se puede llamar al método__clone()de un objeto directamente.

$copia_de_objeto = clone $objeto;

Cuando se clona un objeto, PHP llevará a cabo una copia superficial de las propiedades del objeto. Las propiedades que sean referencias a otras variables, mantendrán las referencias.

__clone():void

Una vez que la clonación ha finalizado, se llamará al método__clone()del nuevo objeto (si el método__clone()estuviera definido), para permitirle realizar los cambios necesarios sobre sus propiedades.

Ejemplo #1 Clonación de un objeto

<?php
classSubObject
{
static
$instances=0;
public
$instance;

public function
__construct() {
$this->instance= ++self::$instances;
}

public function
__clone() {
$this->instance= ++self::$instances;
}
}

class
MyCloneable
{
public
$object1;
public
$object2;

function
__clone()
{
// Forzamos la copia de this->object, si no
// hará referencia al mismo objeto.
$this->object1= clone$this->object1;
}
}

$obj= newMyCloneable();

$obj->object1= newSubObject();
$obj->object2= newSubObject();

$obj2= clone$obj;


print(
"Objeto Original:\n");
print_r($obj);

print(
"Objeto Clonado:\n");
print_r($obj2);

?>

El resultado del ejemplo sería:

Objeto Original:
MyCloneable Object
(
    [object1] => SubObject Object
        (
            [instance] => 1
        )

    [object2] => SubObject Object
        (
            [instance] => 2
        )

)
Objeto Clonado:
MyCloneable Object
(
    [object1] => SubObject Object
        (
            [instance] => 3
        )

    [object2] => SubObject Object
        (
            [instance] => 2
        )

)

PHP 7.0.0 introdujo la posibilidad de acceder a un miembro del objeto recién clonado en una única expresión:

Ejemplo #2 Acceder a un miembre del objeto recién clonado

<?php
$dateTime
= newDateTime();
echo (clone
$dateTime)->format('Y');
?>

El resultado del ejemplo sería algo similar a:

2016


Comparación de Objetos

Al utilizar el operador de comparación (==), se comparan de una forma sencilla las variables de cada objeto, es decir: dos instancias de un objeto son iguales si tienen los mismos atributos y valores (los valores se comparan con==), y son instancias de la misma clase.

Cuando se utiliza el operador identidad (===), las variables de un objeto son idénticas sí y sólo sí hacen referencia a la misma instancia de la misma clase.

Un ejemplo aclarará estas reglas.

Ejemplo #1 Ejemplo de comparación de objetos en PHP 5

<?php
functionbool2str($bool)
{
if (
$bool===false) {
return
'FALSO';
} else {
return
'VERDADERO';
}
}

function
compararObjetos(&$o1, &$o2)
{
echo
'o1 == o2 : '.bool2str($o1==$o2) ."\n";
echo
'o1 != o2 : '.bool2str($o1!=$o2) ."\n";
echo
'o1 === o2 : '.bool2str($o1===$o2) ."\n";
echo
'o1 !== o2 : '.bool2str($o1!==$o2) ."\n";
}

class
Bandera
{
public
$bandera;

function
__construct($bandera=true) {
$this->bandera=$bandera;
}
}

class
OtraBandera
{
public
$bandera;

function
__construct($bandera=true) {
$this->bandera=$bandera;
}
}

$o= newBandera();
$p= newBandera();
$q=$o;
$r= newOtraBandera();

echo
"Dos instancias de la misma clase\n";
compararObjetos($o,$p);

echo
"\nDos referencias a la misma instancia\n";
compararObjetos($o,$q);

echo
"\nInstancias de dos clases diferentes\n";
compararObjetos($o,$r);
?>

El resultado del ejemplo sería:

Dos instancias de la misma clase
o1 == o2 : VERDADERO
o1 != o2 : FALSO
o1 === o2 : FALSO
o1 !== o2 : VERDADERO

Dos referencias a la misma instancia
o1 == o2 : VERDADERO
o1 != o2 : FALSO
o1 === o2 : VERDADERO
o1 !== o2 : FALSO

Instancias de dos clases diferentes
o1 == o2 : FALSO
o1 != o2 : VERDADERO
o1 === o2 : FALSO
o1 !== o2 : VERDADERO

Nota:

Las extensiones pueden definir sus propias reglas para la comparación de sus objetos (==).



Enlaces estáticos en tiempo de ejecución

Desde su versión 5.3.0, PHP incorpora una nueva funcionalidad llamada enlace estático en tiempo de ejecución ("late static bindings" en inglés) que permite referirse referencias a la clase invocada en un contexto de herencia estática.

De forma más precisa, un enlace estático en tiempo de ejecución funciona almacenando el nombre de clase de la última llamada que no tenga «propagación». En el caso de llamadas a métodos estáticos, se trata de la clase nombrada explícitamente (normalmente la que precede al operador::); en los casos de llamadas a métodos no estáticos, es clase del objeto. Una «llamada con propagación» es una llamada estática que precedida porself::,parent::,static::, o, siguiendo la jerarquía de clases,forward_static_call(). La funciónget_called_class()puede utilizarse para obtener una cadena con el nombre de la clase invocada, ystatic::revela cuál es su alcance.

A esta funcionalidad se le ha llamado «enlace estático en tiempo de ejecución» teniendo en cuenta un punto de vista interno. «Enlace en tiempo de ejecución» viene del hecho de questatic::no será resuelto usando la clase donde el método está definido, sino que en su lugar se calculará utilizando información en tiempo de ejecución. También se le llamó «enlace estático» debido a que se puede utilizar (entre otras cosas) para llamadas a métodos estáticos.

Limitaciones deself::

Las referencias estáticas a la clase en uso, comoself::o__CLASS__, se resuelven empleando la clase a la que pertenece la función:

Ejemplo #1 Uso deself::

<?php
classA{
public static function
who() {
echo
__CLASS__;
}
public static function
test() {
self::who();
}
}

class
BextendsA{
public static function
who() {
echo
__CLASS__;
}
}

B::test();
?>

El resultado del ejemplo sería:

A

Uso de enlaces estático en tiempo de ejecución

Los enlaces estáticos en tiempo de ejecución tratan de resolver esta limitación empleando una palabra reservada que se refiera a la clase invocada inicialmente en tiempo de ejecución; básicamente, una palabra reservada que permita referirse a aBdesdetest(), según el ejemplo anterior. Se decidió no crear una nueva palabra reservada, si no utilizar en su lugarstatic, que ya era reservada.

Ejemplo #2 Uso básico destatic::

<?php
classA{
public static function
who() {
echo
__CLASS__;
}
public static function
test() {
static::
who();// He aquí el enlace estático en tiempo de ejecución
}
}

class
BextendsA{
public static function
who() {
echo
__CLASS__;
}
}

B::test();
?>

El resultado del ejemplo sería:

B

Nota:

En contextos no estáticos, la clase invocada será la clase de la instancia del objeto. Dado que$this->trata de invocar métodos privados desde su mismo ámbito, el uso destatic::puede dar diferentes resultados. Otra diferencia es questatic::sólo puede referirse a propiedades estáticas.

Ejemplo #3 Uso destatic::en un contexto no estático

<?php
classA{
private function
foo() {
echo
"¡Éxito!\n";
}
public function
test() {
$this->foo();
static::
foo();
}
}

class
BextendsA{
/* foo() se copiará en B, por lo tanto su ámbito seguirá siendo A
* y la llamada tendrá éxito */
}

class
CextendsA{
private function
foo() {
/* se reemplaza el método original; el ámbito del nuevo es ahora C */
}
}

$b= newB();
$b->test();
$c= newC();
$c->test();//falla
?>

El resultado del ejemplo sería:

¡Éxito!
¡Éxito!
¡Éxito!


Fatal error:  Call to private method C::foo() from context 'A' in /tmp/test.php on line 9

Nota:

En una llamada que se resuelva como estática, la resolución de enlaces estáticos en tiempo de ejecución se detendrá sin propagarse. Por otra parte, las llamadas estáticas que utilicen palabras reservadas comoparent::oself::sí propagarán la información de llamada.

Ejemplo #4 Llamadas que propagan y que no propagan la información de llamada

<?php
classA{
public static function
foo() {
static::
who();
}

public static function
who() {
echo
__CLASS__."\n";
}
}

class
BextendsA{
public static function
test() {
A::foo();
parent::foo();
self::foo();
}

public static function
who() {
echo
__CLASS__."\n";
}
}
class
CextendsB{
public static function
who() {
echo
__CLASS__."\n";
}
}

C::test();
?>

El resultado del ejemplo sería:

A
C
C



Objetos y referencias

Uno de los puntos clave de la POO de PHP 5 que a menudo se menciona es que "por omisión los objetos se pasan por referencia". Esto no es completamente cierto. Esta sección rectifica esa creencia general, usando algunos ejemplos.

Una referencia en PHP es un alias, que permite a dos variables diferentes escribir sobre un mismo valor. Desde PHP 5, una variable de tipo objeto ya no contiene el objeto en sí como valor. Únicamente contiene un identificador del objeto que le permite localizar al objeto real. Cuando se pasa un objeto como parámetro, o se devuelve como retorno, o se asigna a otra variable, las distintas variables no son alias: guardan una copia del identificador, que apunta al mismo objeto.

Ejemplo #1 Referencias y Objetos

<?php
classA{
public
$foo=1;
}

$a= newA;
$b=$a;// $a y $b son copias del mismo identificador
// ($a) = ($b) = <id>
$b->foo=2;
echo
$a->foo."\n";


$c= newA;
$d= &$c;// $c y $d son referencias
// ($c,$d) = <id>

$d->foo=2;
echo
$c->foo."\n";


$e= newA;

function
foo($obj) {
// ($obj) = ($e) = <id>
$obj->foo=2;
}

foo($e);
echo
$e->foo."\n";

?>

El resultado del ejemplo sería:

2
2
2


Serialización de objetos

serialización de objetos - objetos en sesiones

La funciónserialize()devuelve un string que contiene un flujo de bytes que representa cualquier valor que se pueda almacenar en PHP. Por otra parte,unserialize()puede restaurar los valores originales a partir de dicho string. Al utilizar serialize para guardar un objeto, almacenará todas las variables de dicho objeto. En cambio los métodos no se guardarán, sólo el nombre de la clase.

Para poder deserializar (unserialize()) un objeto, debe estar definida la clase de ese objeto. Es decir, si se tiene un objeto de la clase A, y lo serializamos, se obtendrá un string que haga referencia a la clase A y contenga todas las variables que haya en esta clase. Si se desea deserializar en otro fichero, antes debe estar presente la definición de la clase A. Esto se puede hacer, por ejemplo, escribiendo la definición de la clase A en un fichero, para después o bien incluirlo, o bien hacer uso de la funciónspl_autoload_register().

<?php
// classa.inc:

classA{
public
$one=1;

public function
show_one() {
echo
$this->one;
}
}

// page1.php:

include("classa.inc");

$a= newA;
$s=serialize($a);
// almacenamos $s en algún lugar en el que page2.php puede encontrarlo.
file_put_contents('store',$s);

// page2.php:

// se necesita para que unserialize funcione correctamente.
include("classa.inc");

$s=file_get_contents('store');
$a=unserialize($s);

// now use the function show_one() of the $a object.
$a->show_one();
?>

Si una aplicación está usando sesiones, y utilizasession_register()para registrar objetos, estos objetos se serializarán automáticamente al final de cada página PHP, y se deserializan también automáticamente en cada una de las siguientes peticiones. Esto significa que, una vez que formen parte de la sesión, estos objetos se podrán utilizar en cualquier página de la aplicación. Sin embargo, la funciónsession_register(): ha sido borrada a partir de PHP 5.4.0

Si una aplicación serializa objetos para su uso posterior, se recomienda encarecidamente que se incluya la definición de la clase en toda la aplicación. Si no se hiciera, se deserializaría el objeto sin una definición de clase, lo cual daría como resultado que PHP definiera al objeto con la clase__PHP_Incomplete_Class_Name, que no tiene métodos, haciendo que el objeto no fuera útil.

Por tanto, si en el ejemplo anterior$ase guardara en una sesión mediantesession_register("a"), sería necesario incluir el ficheroclassa.incen todas las páginas, no sólo enpage1.phpypage2.php.

Más allá del consejo de arriba, observe que también se puede conectar con eventos de serialización y deserialización sobre un objeto usando los métodos__sleep()y__wakeup(). El uso de__sleep()también permite serializar únicamente un subconjunto de propiedades de objetos.



Covarianza y Contravarianza

En PHP 7.2.0, se introdujo la contravarianza parcial mediante la eliminación de las restricciones de tipo en los parámetros de un método hijo. A partir de PHP 7.4.0, se añadió soporte completo de covarianza y contravarianza.

La covarianza permite que el método hijo devuelva un tipo más específico que el tipo de devolución del método de su padre. Mientras que la contravarianza permite que un tipo de parámetro sea menos específico en un método hijo, que el de su padre.

Covarianza

Para ilustrar cómo funciona la covarianza, una simple clase de padre abstracta,Animales creada.Animalse extenderá a las clases hijo,Cat, yDog.

<?php

abstract classAnimal
{
protected
string $name;

public function
__construct(string $name)
{
$this->name=$name;
}

abstract public function
speak();
}

class
DogextendsAnimal
{
public function
speak()
{
echo
$this->name." barks";
}
}

class
CatextendsAnimal
{
public function
speak()
{
echo
$this->name." meows";
}
}

Observe que no hay ningún método que devuelva valores en este ejemplo. Unas pocas fábricas que devuelven un nuevo objeto de tipo claseAnimal,Cat, oDog.

<?php

interfaceAnimalShelter
{
public function
adopt(string $name):Animal;
}

class
CatShelterimplementsAnimalShelter
{
public function
adopt(string $name):Cat// instead of returning class type Animal, it can return class type Cat
{
return new
Cat($name);
}
}

class
DogShelterimplementsAnimalShelter
{
public function
adopt(string $name):Dog// instead of returning class type Animal, it can return class type Dog
{
return new
Dog($name);
}
}

$kitty= (newCatShelter)->adopt("Ricky");
$kitty->speak();
echo
"\n";

$doggy= (newDogShelter)->adopt("Mavrick");
$doggy->speak();

El resultado del ejemplo sería:

Ricky meows
Mavrick barks

Contravarianza

Continuando con el ejemplo anterior con las clasesAnimal,Cat, yDog, una clase llamadaFoodyAnimalFoodserán incluidas, y un métodoeat(AnimalFood $food)es añadido a la clase abstractaAnimal.

<?php

classFood{}

class
AnimalFoodextendsFood{}

abstract class
Animal
{
protected
string $name;

public function
__construct(string $name)
{
$this->name=$name;
}

public function
eat(AnimalFood $food)
{
echo
$this->name." eats ".get_class($food);
}
}

Para ver el comportamiento de la contravención, el métodoeatse sobrescribe en la claseDogpara permitir cualquier tipo de objetoFood. La claseCatpermanece sin cambios.

<?php

classDogextendsAnimal
{
public function
eat(Food $food) {
echo
$this->name." eats ".get_class($food);
}
}

El siguiente ejemplo mostrará el comportamiento de la contravarianza.

<?php

$kitty
= (newCatShelter)->adopt("Ricky");
$catFood= newAnimalFood();
$kitty->eat($catFood);
echo
"\n";

$doggy= (newDogShelter)->adopt("Mavrick");
$banana= newFood();
$doggy->eat($banana);

El resultado del ejemplo sería:

Ricky eats AnimalFood
Mavrick eats Food

¿Pero qué pasa si el (gatito)$kittytrata de (comer)eatla$banana?

$kitty->eat($banana);

El resultado del ejemplo sería:

Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given


Registro de cambios de la POO

Aquí se registran los cambios del modelo de POO de PHP 5. Las descripciones y otras notas respecto a estas nuevas funcionalidades están documentadas dentro de la documentación de POO 5.

VersiónDescripción
7.0.0Definir propiedades (compatibles) en dos rasgos («traits») ya no lanza un error.
5.6.0Añadido: El método__debugInfo().
5.5.0Añadido: La constante mágica::class.
5.5.0Añadido:finallypara manejar excepciones.
5.4.0Añadido:traits.
5.4.0Cambiado: Si una claseabstractadefine una firma para el constructor, ahora se hará cumplir.
5.3.3Cambiado: Los métodos con el mismo nombre que el último elemento de un nombre de clase perteneciente a unespacio de nombresya no serán tratados como unconstructor. Este cambio no afecta a las clases que no pertenecen a un espacio de nombres.
5.3.0Cambiado: Ya no es necesario que los valores predeterminados de los métodos de una clase que implemente un interfaz coincidan con los valores predeterminados de los prototipos de la interfaz.
5.3.0Cambiado: Ahora es posible hacer referencia a la clase utilizando una variable (p.ej.,echo $nombreclase::constante;). La variable no puede contener como valor una palabra reservada (p.ej.,self,parentostatic).
5.3.0Cambiado: Se emite un error de nivelE_WARNINGsi alsobrecargarun método mágico se le declara comoestático. Además, hace necesario que tenga visibilidad pública.
5.3.0Cambiado: Antes de 5.3.0, las excepciones lanzadas en la función__autoload()no podían capturarse en el bloquecatch, y provocaban un error fatal. Ahora, las excepciones lanzadas dentro de la función __autoload pueden capturarse en el bloquecatch, con una única salvedad: Si se lanza una excepción definida por el usuario, esta excepción debería estar disponible. Se puede utilizar recursivamente la función __autoload para cargar automáticamente la clase de la excepción definida por el usuario.
5.3.0Añadido: El método__callStatic.
5.3.0Añadido: El soporte paraheredocynowdocparaconstantesde clase y definición de propiedades. Nota: los valores heredoc deben seguir las mismas reglas que los string de comillas dobles (p.ej., no contener variables).
5.3.0Añadido:Enlaces estáticos en tiempo de ejecución.
5.3.0Añadido: El método__invoke().
5.2.0Cambiado: Al método__toString()sólo se le invocaba cuando se le combinaba conechoo conprint. Pero ahora, se le invoca en cualquier contexto de string (p.ej, enprintf()con el modificador%s) pero no en contextos de otro tipo (p.ej. con el modificador%d). Desde PHP 5.2.0, convertir objetos a string sin el método__toStringemitirá un error de nivelE_RECOVERABLE_ERROR.
5.1.3Cambiado: En versiones anteriores de PHP 5, se consideraba obsoleto el uso devary emitía un error de nivelE_STRICT. Ya no está obsoleto, y por tanto no emite el error.
5.1.0Cambiado: Ahora se invoca al método estático__set_state()en las clases exportadas porvar_export().
5.1.0Añadido: Los métodos__isset()y__unset().




Espacios de nombres

Tabla de contenidos


Resumen de los espacios de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

¿Qué son los espacios de nombres? En su definición más aceptada, los espacios de nombres son una manera de encapsular elementos. Se pueden ver como un concepto abstracto en muchos aspectos. Por ejemplo, en cualquier sistema operativo, los directorios sirven para agrupar ficheros relacionados, actuando así como espacios de nombres para los ficheros que contienen. Como ejemplo, el ficherofoo.txtpuede existir en los directorios/home/gregy/home/otro, pero no pueden coexistir dos copias defoo.txten el mismo directorio. Además, para acceder al ficherofoo.txtfuera del directorio/home/greg, se debe anteponer el nombre del directorio al nombre del fichero, empleando el separador de directorios para así obtener/home/greg/foo.txt. Este mismo principio se extiende a los espacios de nombres en el mundo de la programación.

VersiónDescripción
7.0.0Añadidas las Declaraciones de use en grupo.

En el mundo de PHP, los espacios de nombres están diseñados para solucionar dos problemas con los que se encuentran los autores de bibliotecas y de aplicaciones al crear elementos de código reusable, tales como clases o funciones:

  1. El conflicto de nombres entre el código que se crea y las clases/funciones/constantes internas de PHP o las clases/funciones/constantes de terceros.
  2. La capacidad de apodar (o abreviar) Nombres_Extra_Largos diseñada para aliviar el primer problema, mejorando la legibilidad del código fuente.

Los espacios de nombres de PHP proporcionan una manera para agrupar clases, interfaces, funciones y constantes relacionadas. Un ejemplo de la sintaxis de los espacios de nombres de PHP:

Ejemplo #1 Ejemplo de sintaxis de espacios de nombres

<?php
namespacemi\nombre;// véase la sección "Definir espacios de nombres"

classMiClase{}
function
mifunción() {}
const
MICONSTANTE=1;

$a= newMiClase;
$c= new \mi\nombre\MiClase;// véase la sección "Espacio global"

$a=strlen('hola');// véase la sección "Utilizar espacios de nombres: una
// alternativa a funciones/constantes globales"

$d= namespace\MICONSTANTE;// véase la sección "El operador namespace y
// la constante __NAMESPACE__"
$d=__NAMESPACE__.'\MICONSTANTE';
echo
constant($d);// véase la sección "Espacios de nombres y características dinámicas del lenguaje"
?>

Nota:

Los nombres de los espacios de nombresPHPyphp, y los nombres compuestos a partir de estos (comoPHP\Classes) están reservados para el uso interno del lenguaje y no deben utilizarse en el código del espacio del usuario.



Definir espacios de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Aunque cualquier código de PHP válido puede estar contenido dentro de un espacio de nombres, solamente se ven afectados por espacios de nombres los siguientes tipos de código: clases (incluyendo abstractas y traits), interfaces, funciones y constantes.

Los espacios de nombres se declaran utilizando la palabra reservadanamespace. Un fichero que contenga un espacio de nombres debe declararlo al inicio del mismo, antes que cualquier otro código, con una excepción: la palabra reservadadeclare.

Ejemplo #1 Declarar un único espacio de nombres

<?php
namespaceMiProyecto;

const
CONECTAR_OK=1;
class
Conexión{/* ... */}
function
conectar() {/* ... */}

?>
La única construcción de código permitida antes de la declaración de un espacio de nombres es la sentenciadeclarepara declarar la codificación de un fichero fuente. Además, todo lo que no sea código de PHP no puede preceder a la declaración del espacio de nombres, incluyendo espacios en blanco extra:

Ejemplo #2 Declarar un único espacio de nombres

<html>
<?php
namespaceMiProyecto;// error fatal - el espacio de nombres debe ser la primera sentencia del script
?>

También, a diferencia de otras construcciones de PHP, se puede definir el mismo espacio de nombres en varios ficheros, permitiendo la separación del contenido de un espacio de nombres a través del sistema de ficheros.



Declarar subespacios de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Al igual que los directorios y ficheros, los espacios de nombres de PHP también tienen la capacidad de especificar una jerarquía de nombres de espacios de nombres. Así, un nombre de un espacio de nombres se puede definir con subniveles:

Ejemplo #1 Declarar un único espacio de nombres con jerarquía

<?php
namespaceMiProyecto\Sub\Nivel;

const
CONECTAR_OK=1;
class
Conexión{/* ... */}
function
conectar() {/* ... */}

?>
El ejemplo de arriba crea la constanteMiProyecto\Sub\Nivel\CONECTAR_OK, la claseMiProyecto\Sub\Nivel\Conexióny la funciónMiProyecto\Sub\Nivel\conectar.



Definir varios espacios de nombres en un mismo fichero

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

También se pueden declarar varios espacios de nombres en un mismo fichero. Se permiten dos tipos de sintaxis.

Ejemplo #1 Declarar varios espacios de nombres, sintaxis de combinación simple

<?php
namespaceMiProyecto;

const
CONECTAR_OK=1;
class
Conexión{/* ... */}
function
conectar() {/* ... */}

namespace
OtroProyecto;

const
CONECTAR_OK=1;
class
Conexión{/* ... */}
function
conectar() {/* ... */}
?>

No se recomienda esta sintaxis para combinar espacios de nombres en un único fichero. En su lugar, se recomienda emplear la sintaxis de llaves alternativa.

Ejemplo #2 Declarar varios espacios de nombres, sintaxis de llaves

<?php
namespaceMiProyecto{

const
CONECTAR_OK=1;
class
Conexión{/* ... */}
function
conectar() {/* ... */}
}

namespace
OtroProyecto{

const
CONECTAR_OK=1;
class
Conexión{/* ... */}
function
conectar() {/* ... */}
}
?>

Se desaconseja completamente, como práctica de código, la combinación de varios espacios de nombres en un mismo fichero. El caso de uso principal es combinar varios scripts de PHP en el mismo fichero.

Combinar código global que no es de espacio de nombres con código que sí lo es, sólo está soportado mediante la sintaxis de llaves. El código global debería estar encerrado en una declaración de espacio de nombres sin nombre de espacio de nombres:

Ejemplo #3 Declarar múltiples espacios de nombres y código que no es de espacio de nombres

<?php
namespaceMiProyecto{

const
CONECTAR_OK=1;
class
Conexión{/* ... */}
function
conectar() {/* ... */}
}

namespace {
// código global
session_start();
$a=MiProyecto\conectar();
echo
MiProyecto\Conexión::iniciar();
}
?>

No puede existir código de PHP fuera de las llaves del espacio de nombres, excepto para una sentencia de apertura 'declare'.

Ejemplo #4 Declarar varios espacios de nombres y código que no es de espacio de nombres

<?php
declare(encoding='UTF-8');
namespace
MiProyecto{

const
CONECTAR_OK=1;
class
Conexión{/* ... */}
function
conectar() {/* ... */}
}

namespace {
// código global
session_start();
$a=MiProyecto\conectar();
echo
MiProyecto\Conexión::iniciar();
}
?>



Uso de los espacios de nombres: lo básico

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Antes de hablar del uso de los espacios de nombres es importante entender cómo sabe PHP qué elemento del código del espacio de nombres se requiere. Se puede hacer una simple analogía entre los espacios de nombres de PHP y el sistema de ficheros. Existen tres maneras de acceder a un fichero en el sistema de ficheros:

  1. Nombre de fichero relativo comofoo.txt. Se resuelve condirectorio_actual/foo.txtdonde directorio_actual es el directorio actualmente ocupado. Así, si el directorio actual es/home/foo, el nombre se resuelve con/home/foo/foo.txt.
  2. Nombre de ruta relativa comosubdirectorio/foo.txt. Se resuelve condirectorioactual/subdirectorio/foo.txt.
  3. Nombre de ruta absoluta como/main/foo.txt. Se resuelve con/main/foo.txt.
Se puede aplicar el mismo principio a los elementos del espacio de nombres de PHP. Por ejemplo, se puede hacer referencia a un nombre de una clase de tres maneras:
  1. Nombre no cualificado, o nombre de clase sin prefijo como$a = new foo();ofoo::método_estático();. Si el espacio de nombres actual esespacio_de_nombres_actual, esto se resuelve conespacio_de_nombres_actual\foo. Si el código es global, es decir, no es de espacio de nombres, esto se resuelve confoo.Una advertencia: los nombres no cualificados para funciones y constantes se resolverán con funciones y constantes globales si la función o la constante del espacio de nombres no está definida. VéaseUtilizar espacios de nombres: una alternativa a funciones/constantes globalespara más detalles.
  2. Nombre cualificado, o un nombre de clase con prefijo como$a = new subespacio_de_nombres\foo();osubespacio_de_nombres\foo::método_estático();. Si el espacio de nombres actual esespacio_de_nombres_actual, esto se resuelve conespacio_de_nombres_actual\subespacio_de_nombres\foo. Si el código es global, es decir, no es de espacio de nombres, esto se resuelve consubespacio_de_nombres\foo.
  3. Nombre completamente cualificado, o un nombre con prefijo con el operador de prefijo global como$a = new \espacio_de_nombres_actual\foo();o\espacio_de_nombres_actual\foo::método_estático();. Esto siempre se resuelve con nombre literal especificado en el código,espacio_de_nombres_actual\foo.

Un ejemplo de los tres tipos de sintaxis en código real:

fichero1.php

<?php
namespaceFoo\Bar\subespacio_de_nombres;

const
FOO=1;
function
foo() {}
class
foo
{
static function
método_estático() {}
}
?>

fichero2.php

<?php
namespaceFoo\Bar;
include
'fichero1.php';

const
FOO=2;
function
foo() {}
class
foo
{
static function
método_estático() {}
}

/* Nombre no cualificado */
foo();// se resuelve con la función Foo\Bar\foo
foo::método_estático();// se resuelve con la clase Foo\Bar\foo, método método_estático
echoFOO;// se resuelve con la constante Foo\Bar\FOO

/* Nombre cualificado */
subespacio_de_nombres\foo();// se resuelve con la función Foo\Bar\subespacio_de_nombres\foo
subespacio_de_nombres\foo::método_estático();// se resuelve con la clase Foo\Bar\subespacio_de_nombres\foo,
// método método_estático
echosubespacio_de_nombres\FOO;// se resuelve con la constante Foo\Bar\subespacio_de_nombres\FOO

/* Nombre conmpletamente cualificado */
\Foo\Bar\foo();// se resuelve con la función Foo\Bar\foo
\Foo\Bar\foo::método_estático();// se resuelve con la clase Foo\Bar\foo, método método_estático
echo \Foo\Bar\FOO;// se resuelve con la constante Foo\Bar\FOO
?>

Observe que para acceder a cualquier clase, función o constante globales, se puede utilizar un nombre completamente cualificado, como\strlen()o\Exceptiono\INI_ALL.

Ejemplo #1 Acceder a clases, funciones y constantes globales desde un espacio de nombres

<?php
namespaceFoo;

function
strlen() {}
const
INI_ALL=3;
class
Exception{}

$a= \strlen('hola');// llama a la función global strlen
$b= \INI_ALL;// accede a la constante global INI_ALL
$c= new \Exception('error');// instancia a la clase global Exception
?>



Espacios de nombres y características dinámicas del lenguaje

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

La implementación de PHP de los espacios de nombres está influenciada por su naturaleza dinámica como lenguaje de programación. Así, para convertir código como el del siguiente ejemplo en código de espacios de nombres:

Ejemplo #1 Acceder dinámicamente a elementos

ejemplo1.php:

<?php
classnombre_clase
{
function
__construct()
{
echo
__METHOD__,"\n";
}
}
function
nombre_func()
{
echo
__FUNCTION__,"\n";
}
const
nombre_const="global";

$a='nombre_clase';
$obj= new$a;// imprime nombre_clase::__construct
$b='nombre_func';
$b();// imprime nombre_func
echoconstant('nombre_const'),"\n";// imprime global
?>
se debe emplear el nombre completamente cualificado (nombre de clase con prefijo de espacio de nombres). Observe que, debido a que no hay diferencia entre un nombre cualificado y uno completamente cualificado dentro de un nombre de clase, función, o constante dinámicas, no es necesario la barra invertida inicial.

Ejemplo #2 Acceder dinámicamente a elementos de un espacio de nombres

<?php
namespacenombre_espacio_de_nombres;
class
nombre_clase
{
function
__construct()
{
echo
__METHOD__,"\n";
}
}
function
nombre_func()
{
echo
__FUNCTION__,"\n";
}
const
nombre_const="de espacio de nombres";

/* observe que si se emplean comillas dobles, se debe usar "\\nombre_espacio_de_nombres\\nombre_clase" */
$a='\nombre_espacio_de_nombres\nombre_clase';
$obj= new$a;// imprime nombre_espacio_de_nombres\nombre_clase::__construct
$a='nombre_espacio_de_nombres\nombre_clase';
$obj= new$a;// también imprime nombre_espacio_de_nombres\nombre_clase::__construct
$b='nombre_espacio_de_nombres\nombre_func';
$b();// imprime nombre_espacio_de_nombres\nombre_func
$b='\nombre_espacio_de_nombres\nombre_func';
$b();// también imprime nombre_espacio_de_nombres\nombre_func
echoconstant('\nombre_espacio_de_nombres\nombre_const'),"\n";// imprime de espacio de nombres
echoconstant('nombre_espacio_de_nombres\nombre_const'),"\n";// también imprime de espacio de nombres
?>

Asegúrese de leer lanota sobre escapar nombres de espacios de nombres en cadenas.



La palabra reservada namespace y la constante __NAMESPACE__

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP admite dos formas de acceder de manera abstracta a elementos dentro del espacio de nombres actual: la constante mágica__NAMESPACE__, y la palabra reservadanamespace.

El valor de__NAMESPACE__es una cadena que contiene el nombre del espacio de nombres actual. En código global, que no es de espacio de nombres, contiene una cadena vacía.

Ejemplo #1 Ejemplo de __NAMESPACE__, código de espacio de nombres

<?php
namespaceMiProyecto;

echo
'"',__NAMESPACE__,'"';// imprime "MiProyecto"
?>

Ejemplo #2 Ejemplo de __NAMESPACE__, código global

<?php

echo'"',__NAMESPACE__,'"';// imprime ""
?>
La constante__NAMESPACE__es útil para construir nombres dinámicamente, por ejemplo:

Ejemplo #3 Empleo de __NAMESPACE__ para la construcción dinámica de nombres

<?php
namespaceMiProyecto;

function
obtener($nombre_clase)
{
$a=__NAMESPACE__.'\\'.$nombre_clase;
return new
$a;
}
?>

La palabra reservadanamespacese puede utilizar para solicitar explícitamente un elemento del espacio de nombres o subespacio de nombres actual. Es el equivalente del espacio de nombres para el operadorselfde las clases.

Ejemplo #4 El operador namespace, dentro de un espacio de nombres

<?php
namespaceMiProyecto;

use
blah\blahasmío;// véase "Uso de los espacios de nombres: Apodar/Importar"

blah\mío();// llama a la función MiProyecto\blah\mío()
namespace\blah\mío();// llama a la función MiProyecto\blah\mío()

namespace\func();// llama a la función MiProyecto\func()
namespace\sub\func();// llama a la función MiProyecto\sub\func()
namespace\nombrec::método();// llama al método estático "método" de la clase MiProyecto\nombrec
$a= new namespace\sub\nombrec();// instancia un objeto de la clase MiProyecto\sub\nombrec
$b= namespace\CONSTANTE;// asigna el valor de la constante MiProyecto\CONSTANTE a $b
?>

Ejemplo #5 El operador namespace, en código global

<?php

namespace\func();// llama a la función func()
namespace\sub\func();// llama a la función sub\func()
namespace\nombrec::método();// llama al método estático "método" de la clase nombrec
$a= new namespace\sub\nombrec();// instancia un objeto de la clase sub\nombrec
$b= namespace\CONSTANTE;// asigna el valor de la constante CONSTANTE a $b
?>



Uso de los espacios de nombres: apodar/importar

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

La capacidad de referirse a un nombre completamente cualificado externo con un alias, o importar, es una característca importante de los espacios de nombres. Esto es similar a la capacidad de los sistemas de ficheros basados en Unix de crear enlaces simbólicos a un fichero o directorio.

Todas las versiones de PHP que tienen soporte para espacios de nombres admiten tres tipos de alias o importación: apodar un nombre de clase, apodar un nombre de interfaz, y apodar un nombre de espacio de nombres. PHP 5.6+ también permite apodar o importar nombres de funciones y constantes.

En PHP, la acción de apodar se lleva a cabo con el operadoruse. Aquí hay un ejemplo que muestra los cinco tipos de importación:

Ejemplo #1 Importar/apodar con el operador use

<?php
namespacefoo;
use
Mi\Completo\NombreDeClaseasOtra;

// esto es lo mismo que utilizar Mi\Completo\NombreEN as NombreEN
useMi\Completo\NombreEN;

// importar una clase global
useArrayObject;

// importar una función (PHP 5.6+)
use functionMi\Completo\nombreDeFunción;

// apodar una función (PHP 5.6+)
use functionMi\Completo\nombreDeFunciónasfunc;

// importar una constante (PHP 5.6+)
use constMi\Completa\CONSTANTE;

$obj= new namespace\Otra;// instancia un objeto de la clase foo\Otra
$obj= newOtra;// instancia un objeto de la clase class Mi\Completo\NombreDeClase
NombreEN\suben\func();// llama a la función Mi\Completo\NombreEN\subes\func
$a= newArrayObject(array(1));// instancia un objeto de la clase ArrayObject
// sin el "use ArrayObject" instanciaríamos un objeto de la clase foo\ArrayObject
func();// llama a la función Mi\Completo\nombreDeFunción
echoCONSTANT;// imprime el valor de Mi\Completa\CONSTANTE;
?>
Observe que para los nombres de espacios de nombres (nombres de espacios de nombres completamente cualificados que contienen el separador de espacios de nombres, comoFoo\Bar, en oposición a los nombres globales que no lo contienen, comoFooBar), no es necesaria y no está recomendada la barra invertida inicial, ya que los nombres importados deben ser completamente cualificados, por lo que no son procesados en relación al espacio de nombres actual.

PHP admite además un atajo para poner varias sentencias use en la misma línea

Ejemplo #2 Importar/apodar con el operador use, varias sentencias use combinadas

<?php
useMi\Completo\NombreDeClaseasOtra,Mi\Completo\NombreEN;

$obj= newOtra;// instancia un objeto de la clase Mi\Completo\NombreDeClase
NombreEN\suben\func();// llama a la función Mi\Completo\NombreEN\suben\func
?>

La importación se realiza durante la compilación, por lo que no afecta a los nombres de clases, funciones o constantes.

Ejemplo #3 La importación y los nombres dinámicos

<?php
useMi\Completo\NombreDeClaseasOtra,Mi\Completo\NombreEN;

$obj= newOtra;// instancia un objeto de la clase Mi\Completo\NombreDeClase
$a='Otra';
$obj= new$a;// instancia un objeto de la clase Otra
?>

Además, la importación sólo afecta a los nombres cualificados y no cualificados. Los nombres completamente cualificados son absolutos, por lo que no se ven afectados por la importación.

Ejemplo #4 La importación y los nombres completamente cualificados

<?php
useMi\Completo\NombreDeClaseasOtra,Mi\Completo\NombreEN;

$obj= newOtra;// instancia un objeto de la clase Mi\Completo\NombreDeClase
$obj= new \Otra;// instancia un objeto de la clase Otra
$obj= newOtra\cosa;// instancia un objeto de la clase Mi\Completo\NombreDeClase\cosa
$obj= new \Otra\cosa;// instancia un objeto de la clase Otra\cosa
?>

Reglas de ámbito para la importación

La palabra reservadausedebe ser declarada en el ámbito exterior de un fichero (el ámbito global) o dentro de declaraciones de espacios de nombres. Esto es así debido a que la importación se realiza durante la compilación y no durante la ejecución, por lo que no puede ser utilizada en un ámbito de bloque. El siguiente ejemplo muestra un uso ilegal de la palabra reservadause:

Ejemplo #5 Regla de importación ilegal

<?php
namespaceIdiomas;

function
aGroenlandés
{
use
Idiomas\Danés;

// ...
}
?>

Nota:

Las reglas de importación tiene una base por fichero, lo que significa que los ficheros incluidosNOheredarán las reglas de importación del padre.

Declaraciones deuseen grupo

Desde PHP 7.0 en adelante, las clases, funciones y constantes importadas desde el mismonamespacepueden ser agrupadas en una única sentenciause.

<?php

// Código anterir a PHP 7
useun\espacioDeNombres\ClaseA;
use
un\espacioDeNombres\ClaseB;
use
un\espacioDeNombres\ClaseCasC;

use function
un\espacioDeNombres\fn_a;
use function
un\espacioDeNombres\fn_b;
use function
un\espacioDeNombres\fn_c;

use const
un\espacioDeNombres\ConstA;
use const
un\espacioDeNombres\ConstB;
use const
un\espacioDeNombres\ConstC;

// Código de PHP 7+
useun\espacioDeNombres\{ClaseA,ClaseB,ClaseCasC};
use function
un\espacioDeNombres\{fn_a,fn_b,fn_c};
use const
un\espacioDeNombres\{ConstA,ConstB,ConstC};


Espacio global

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Sin ninguna definición de espacios de nombres, todas las definiciones de clases y funciones son colocadas en el espacio global, como si lo estuvieran antes de que PHP soportara los espacios de nombres. Prefijar un nombre con\especificará que el nombre es requerido desde el espacio global incluso en el contexto del espacio de nombres.

Ejemplo #1 Usar la especificación de espacio global

<?php
namespaceA\B\C;

/* Esta función es A\B\C\fopen */
functionfopen() {
/* ... */
$f= \fopen(...);// llamar a fopen global
return$f;
}
?>



Utilizar espacios de nombres: una alternativa a funciones/constantes globales

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Dentro de un espacio de nombres, cuando PHP se encuentra con nombre no cualificado en un contexto de nombre de clase, función o constante, lo resuelve con diferentes prioridades. Los nombres de clases siempre se resuelven con el nombre de espacio de nombres actual. Así, para acceder a clases de usuario internas o que no son de espacio de nombres, se debe referir a ellas con su nombre completamente cualificado:

Ejemplo #1 Acceder a clases globales dentro de un espacio de nombres

<?php
namespaceA\B\C;
class
Exceptionextends \Exception{}

$a= newException('hola');// $a es un objeto de la clase A\B\C\Exception
$b= new \Exception('hola');// $b es un objeto de la clase Exception

$c= newArrayObject;// error fatal, no se encontró la clase A\B\C\ArrayObject
?>

Para funciones y constantes, PHP recurrirá a funciones y constantes globales si no existe una función o constante en el espacio de nombres.

Ejemplo #2 Recurrir a funciones/constantes globales dentro de un espacio de nombres

<?php
namespaceA\B\C;

const
E_ERROR=45;
function
strlen($str)
{
return \
strlen($str) -1;
}

echo
E_ERROR,"\n";// imprime "45"
echoINI_ALL,"\n";// imprime "7" - recurre a INI_ALL global

echostrlen('hola'),"\n";// imprime "3"
if (is_array('hola')) {// imprime "no es un array"
echo"es una array\n";
} else {
echo
"no es un array\n";
}
?>



Reglas de resolución de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

A continuación se exponen unas definiciones importantes para estas reglas de resolución:

Definiciones de nombres de espacios de nombres
Nombre no cualificado

Es un identificador sin un separador de espacios de nombres, comoFoo

Nombre cualificado

Es un identificador con un separador de espacios de nombres, comoFoo\Bar

Nombre completamente cualificado

Es un identificador con un separador de espacios de nombres que comienza con un separador de espacios de nombres, como\Foo\Bar.namespace\Footambién es un nombre completamente cualificado.

Los nombres se resuelven siguiendo estas reglas de resolución:

  1. Las llamadas a clases, funciones o constantes completamente cualificadas se resuelven durante la compilación. Por ejemplonew \A\Bse resuelve con la claseA\B.
  2. Todos los nombres no cualificados y cualificados (no los completamente cualificados) se traducen durante la compilación según las reglas de importación actuales. Por ejemplo, si el espacio de nombresA\B\Cse importa comoC, una llamada aC\D\e()se traduce comoA\B\C\D\e().
  3. Dentro de un espacio de nombres, todos los nombres cualificados no traducidos según la reglas de importación llevan antepuesto el espacio de nombres actual. Por ejemplo, si una llamada aC\D\e()se lleva a cabo dentro del espacio de nombresA\B, se traduce comoA\B\C\D\e().
  4. Los nombres de clases no cualificados se traducen durante la compilación según las reglas de importación actuales (el nombre completo sustituido por el nombre abreviado importado). Por ejemplo, si el espacio de nombresA\B\Cse importa como C,new C()se traduce comonew A\B\C().
  5. Dentro de un espacio de nombres (digamos A\B), las llamadas a funciones no cualificadas se resuelven durante la ejecución. Así se resuelve una llamada a la funciónfoo():
    1. Se busca una función del espacio de nombres actual:A\B\foo().
    2. Se intenta encontrar y llamar a la funciónglobalfoo().
  6. Dentro de un espacio de nombres (digamosA\B), las llamadas a nombres de clases no cualificados o cualificados (no los completamente cualificados) se resuelven durante la ejecución. Así se resuelve una llamada anew C()o anew D\E(). Paranew C():
    1. Se busca una clase del espacio de nombres actual:A\B\C.
    2. Se intenta autocargarA\B\C.
    Paranew D\E():
    1. Se busca una clase anteponiendo el espacio de nombres actual:A\B\D\E.
    2. Se intenta autocargarA\B\D\E.
    Para referirse a cualquier clase global en el espacio de nombres global, se debe emplear su nombre completamente cualificadonew \C().

Ejemplo #1 Las resoluciones de nombres ilustradas

<?php
namespaceA;
use
B\D,C\EasF;

// llamadas a funciones

foo();// primero se intenta llamar a "foo" definida en el espacio de nombres "A"
// después se llama a la función global "foo"

\foo();// se llama a la función "foo" definidia en el ámbito global

mi\foo();// se llama a la función "foo" definida en el espacio de nombres "A\mi"

F();// primero se intenta llamar a "F" definida en el espacio de nombres "A"
// después se llama a la función global "F"

// referecias a clases

newB();// crea un objeto de la clase "B" definida en el espacio de nombres "A"
// si no se encuentra, se intenta autocargar la clase "A\B"

newD();// usando las reglas de importación, se crea un objeto de la clase "D" definida en el espacio de nombres "B"
// si no se encuentra, se intenta autocargar la clase "B\D"

newF();// usando las reglas de importación, se crea un objeto de la clase "E" definida en el espacio de nombres "C"
// si no se encuentra, se intenta autocargar la clase "C\E"

new \B();// crea un objeto de la clase "B" definida en el ámbito global
// si no se encuentra, se intenta autocargar la clase "B"

new \D();// crea un objeto de la clase "D" definida en el ámbito global
// si no se encuentra, se intenta autocargar la clase "D"

new \F();// crea un objeto de la clase "F" definida en el ámbito global
// si no se encuentra, se intenta autocargar la clase "F"

// métodos estáticos y funciones de un espacio de nombres desde otro espacio de nombres

B\foo();// se llama a la función "foo" desde el espacio de nombres "A\B"

B::foo();// se llama al método "foo" de la clase "B" definidia en el espacio de nombres "A"
// si no se encuentra la clase "A\B", se intenta autocargar la clase "A\B"

D::foo();// usando las reglas de importación, se llama al método "foo" de la clase "D" definida en el espacio de nombres "B"
// si no se encuentra la clase "B\D", se intenta autocargar la clase "B\D"

\B\foo();// se llama a la función "foo" desde el espacio de nombres "B"

\B::foo();// se llama al método "foo" de la clase "B" desde el ámbito global
// si no es encuentra la clase "B", se intenta autocargar la clase "B"

// métodos estáticos yfunciones de un espacio de nombres del espacio de nombres actual

A\B::foo();// se llama al método "foo" de la clase "B" desde el espacio de nombres "A\A"
// si no se encuentra la clase "A\A\B", se intenta autocargar la clase "A\A\B"

\A\B::foo();// se llama al método "foo" de la clase "B" desde el espacio de nombres "A"
// si no se encuentra la clase "A\B", se intenta autocargar la clase "A\B"
?>


P+F: cosas que es necesario saber sobre los espacios de nombres

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Esta sección está dividida en dos subsecciones: preguntas comunes, y algunas especificaciones de implementación que son útiles para comprender completamente los espacios de nombres.

Primero, las preguntas comunes.

  1. Si no utilizo espacios de nombres, ¿debería preocuparme por algo de esto?
  2. ¿Cómo uso clases internas o globales en un espacio de nombres?
  3. ¿Cómo uso clases, funciones o constantes de espacios de nombres en su propio espacio de nombres?
  4. ¿Cómo se resuelve un nombre como\mi\nombreo\nombre?
  5. ¿Cómo se resuelve un nombre comomi\nombre?
  6. ¿Cómo se resuelve un nombre de clase no cualificado comonombre?
  7. ¿Cómo se resuelve un nombre de función o de constante no cualifcado comonombre?

Existen unos pocos detalles de las implementaciones de espacios de nombres que son útiles para enterderlos.

  1. Importar nombres no entra en conflicto con las clases definidas en el mismo fichero.
  2. Los espacios de nombres anidados no están permitidos.
  3. Antes de PHP 5.6, ni las funciones ni las constantes se pueden importar mediante la sentenciause.
  4. Los nombres de espacios de nombres dinámicos (identificadores entre comillas) deberían escaparse con una barra invertida.
  5. Las constantes no definidas aludidas usando cualquier barra invertida terminan en un error fatal
  6. No se pueden sobrescribir las constantes especiales NULL, TRUE, FALSE, ZEND_THREAD_SAFE o ZEND_DEBUG_BUILD

Si no utilizo espacios de nombres, ¿debería preocuparme por algo de esto?

No. Los espacios de nombres no afectan a ningún código existente de ninguna manera, o a ningún código todavía por escribir que no contenga espacios de nombres. Se puede escribir este código si se desea:

Ejemplo #1 Acceder a clases globales fuera de un espacio de nombres

<?php
$a
= new \stdClass;
?>

Esto es funcionalmente equivalente a:

Ejemplo #2 Acceder a clases globales fuera de un espacio de nombres

<?php
$a
= newstdClass;
?>

¿Cómo uso clases internas o globales en un espacio de nombres?

Ejemplo #3 Acceder a clases internas en espacios de nombres

<?php
namespacefoo;
$a= new \stdClass;

function
probar(\ArrayObject $ejemploalusiónatipo=null) {}

$a= \DirectoryIterator::CURRENT_AS_FILEINFO;

// extender una clase interna o global
classMiExcepciónextends \Exception{}
?>

¿Cómo uso clases, funciones o constantes de espacios de nombres en su propio espacio de nombres?

Ejemplo #4 Acceder a clases, funciones o constantes internas en un espacio de nombres

<?php
namespacefoo;

class
MiClase{}

// usar una clase desde el espacio de nombres actual como una declaración de tipo
functionprobar(MiClase $ejemploalusiónatipo=null) {}
// otra manera de usar una clase desde el espacio de nombres actual una declaración de tipo
functionprobar(\foo\MiClase $ejemploalusiónatipo=null) {}

// extender una clase desde el espacio de nombres actual
classExtendidaextendsMiClase{}

// acceder a una función global
$a= \funcglobal();

// acceder a una constante global
$b= \INI_ALL;
?>

¿Cómo se resuelve un nombre como\mi\nombreo\nombre?

Los nombres que comienzan con una\siempre se resuelven a aquello a lo que se asemejan, así\mi\nombrede hecho esmi\nombre, y\ExceptionesException.

Ejemplo #5 Nombres completamente cualificados

<?php
namespacefoo;
$a= new \mi\nombre();// instancia a la clase "mi\nombre"
echo \strlen('hola');// llama a la función "strlen"
$a= \INI_ALL;// $a está establecida al valor de la constante "INI_ALL"
?>

¿Cómo se resuelve un nombre comomi\nombre?

Los nombres que contienen una barra invertida pero no comienzan con una barra invertida comomi\nombrepueden resolverse de dos formas diferentes.

Si hay una sentencia de importación que apode a otro nombre comomi, el alias de importación se aplica amienmi\nombre.

De lo contrario, al nombre del espacio de nombres actual se le anteponemi\nombre.

Ejemplo #6 Nombres cualificados

<?php
namespacefoo;
use
blah\blahasfoo;

$a= newmi\nombre();// instancia a la clase "foo\mi\nombre"
foo\bar::nombre();// llama a método estático "nombre" de la clase "blah\blah\bar"
mi\bar();// llama a la función "foo\mi\bar"
$a=mi\BAR;// establece $a al valor de la constante "foo\mi\BAR"
?>

¿Cómo se resuelve un nombre de clase no cualificado comonombre?

Los nombres de clases que no contienen una barra invertida comonombrese pueden resolver de dos formas diferentes.

Si hay una sentencia de importación que apode a otro nombre comonombre, se aplica el alias de importación.

De lo contrario, al nombre del espacio de nombres actual se le anteponenombre.

Ejemplo #7 Nombres de clases no cualificados

<?php
namespacefoo;
use
blah\blahasfoo;

$a= newnombre();// instancia a la clase "foo\nombre"
foo::nombre();// llama al método estático "nombre" de la clase "blah\blah"
?>

¿Cómo se resuelve un nombre de función o de constante no cualifcado comonombre?

Los nombres de funciones o de constantes que no contienen una barra invertida comonombrese pueden resolver de dos formas diferentes.

Primero, al nombre del espacio de nombres actual se le anteponenombre.

Finalmente, si elnombrede la constante o de la función no existe en el espacio de nombres actual, se emplea unnombrede constante o función global, si es que existe.

Ejemplo #8 Nombres de funciones o constantes no cualificados

<?php
namespacefoo;
use
blah\blahasfoo;

const
FOO=1;

function
mi() {}
function
foo() {}
function
sort(&$a)
{
\
sort($a);// invoca a la función global "sort"
$a=array_flip($a);
return
$a;
}

mi();// calls "foo\mi"
$a=strlen('hola');// llama a la función global "strlen" ya que "foo\strlen" no existe
$array= array(1,3,2);
$b=sort($array);// llama a la función "foo\sort"
$c=foo();// llama a la función "foo\foo" - la importación no se aplica

$a=FOO;// establece $a al valor de la constante "foo\FOO"; la importación no se aplica
$b=INI_ALL;// establece $b al valor de la constante "INI_ALL"
?>

Importar nombres no entra en conflicto con las clases definidas en el mismo fichero.

Están permitidas las siguientes combinaciones de scripts:

fichero1.php

<?php
namespacemis\cosas;
class
MiClase{}
?>

otro.php

<?php
namespaceotro;
class
cosa{}
?>

fichero2.php

<?php
namespacemis\cosas;
include
'fichero1.php';
include
'otro.php';

use
otro\cosaasMiClase;
$a= newMiClase;// instancia a la clase "cosa" del espacio de nombres otro
?>

No existe conflicto entre nombres, aunque la claseMiClaseexista dentro del espacio de nombresmis\cosas, porque la definición de MiClase está en otro fichero. Sin embargo, el siguiente ejemplo causa un error fatal por el conflicto entre nombres, debido a que MiClase está definida en el mismo fichero que el de la sentencia use.

<?php
namespacemis\cosas;
use
otro\cosaasMiClase;
class
MiClase{}// error fatal: MiClase entra en conflicto con la sentencia de importación
$a= newMiClase;
?>

Los espacios de nombres anidados no están permitidos.

PHP no permite los espacios de nombres anidados

<?php
namespacemis\cosas{
namespace
anidado{
class
foo{}
}
}
?>
Sin embargo, es fácil simular los espacios de nombres anidados de la siguiente manera:
<?php
namespacemis\cosas\anidado{
class
foo{}
}
?>

Antes de PHP 5.6, ni las funciones ni las constantes se pueden importar mediante la sentenciause.

Ants de PHP 5.6, los únicos elementos que se ven afectados por la sentenciauseson los espacios de nombres y los nombres de clases. Para abreviar una constante o una función larga, se ha de importar el espacio de nombres que la contiene:

<?php
namespacemío;
use
nombre\en\ultra\largo;

$a=largo\CONSTANT;
largo\func();
?>
A partir de PHP 5.6, está permitido apodar o imortar nombres de funciones y de constantes.

Los nombres de espacios de nombres dinámicos (identificadores entre comillas) deberían escaparse con una barra invertida.

Es muy importante darse cuenta de que, debeido a que la barra invertida se usa como carácter de escape dentro de cadenas, se deberían emplear dos barras inverticas cuando se utilicen dentro de cadenas. De lo contrario, existe el riesgo de obtener consecuencias inesperadas:

Ejemplo #9 Peligros de usar nombres de espacios de nombres dentro de una cadena entre comillas dobles

<?php
$a
="peligroso\nombre";// ¡\n es una nueva línea dentro de las cadenas entre comillas dobles!
$obj= new$a;

$a='sin\peligro\alguno';// aquí sin problemas.
$obj= new$a;
?>
Dentro de una cadena entre comillas dobles, es más seguro usar la secuencia de escape de la barra invertida, pero aún se recomienda como práctica escapar las barras invertidas en todas las cadenas.

Las constantes no definidas a las que se hace referencia usando una barra invertida terminan con un error fatal

Cualquier constante no definida que no sea cualificada, comoFOO, generará una aviso explicando que PHP asume queFOOes el valor de la constante. Cualquier constante, cualificada o completamente cualificada, que contenga una barra invertida producirá un error fatal si no se encuentra.

Ejemplo #10 Constantes no definidas

<?php
namespacebar;
$a=FOO;// produce un aviso - constante no definida "FOO" se asume que es "FOO";
$a= \FOO;// error fatal, constante FOO del espacio de nombres no definida
$a=Bar\FOO;// error fatal, constante bar\Bar\FOO del espacio de nombres no definida
$a= \Bar\FOO;// error fatal, constante Bar\FOO del espacio de nombres no definida
?>

No se pueden sobrescribir las constantes especiales NULL, TRUE, FALSE, ZEND_THREAD_SAFE o ZEND_DEBUG_BUILD

Cualquier intento de definir una constante de espacio de nombres que sea una constante especial interna, resultará en un error fatal:

Ejemplo #11 Constantes no definidas

<?php
namespacebar;
const
NULL=0;// error fatal;
consttrue='estúpido';// también error fatal;
// etc.
?>




Enumerations

Tabla de contenidos


Enumerations overview

(PHP 8 >= 8.1.0)

Enumerations, or "Enums" allow a developer to define a custom type that is limited to one of a discrete number of possible values. That can be especially helpful when defining a domain model, as it enables "making invalid states unrepresentable."

Enums appear in many languages with a variety of different features. In PHP, Enums are a special kind of object. The Enum itself is a class, and its possible cases are all single-instance objects of that class. That means Enum cases are valid objects and may be used anywhere an object may be used, including type checks.

The most popular example of enumerations is the built-in boolean type, which is an enumerated type with legal valuestrueandfalse. Enums allows developers to define their own arbitrarily robust enumerations.



Basic enumerations

Enums are similar to classes, and share the same namespaces as classes, interfaces, and traits. They are also autoloadable the same way. An Enum defines a new type, which has a fixed, limited number of possible legal values.

<?php
enum Suit
{
case
Hearts;
case
Diamonds;
case
Clubs;
case
Spades;
}
?>

This declaration creates a new enumerated type namedSuit, which has four and only four legal values:Suit::Hearts,Suit::Diamonds,Suit::Clubs, andSuit::Spades. Variables may be assigned to one of those legal values. A function may be type checked against an enumerated type, in which case only values of that type may be passed.

<?php
functionpick_a_card(Suit $suit) { ... }

$val=Suit::Diamonds;

// OK
pick_a_card($val);
// OK
pick_a_card(Suit::Clubs);
// TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
pick_a_card('Spades');
?>

An Enumeration may have zero or morecasedefinitions, with no maximum. A zero-case enum is syntactically valid, if rather useless.

For Enumeration cases, the same syntax rules apply as to any label in PHP, seeConstants.

By default, cases are not intrinsically backed by a scalar value. That is,Suit::Heartsis not equal to"0". Instead, each case is backed by a singleton object of that name. That means that:

<?php
$a
=Suit::Spades;
$b=Suit::Spades;

$a===$b;// true

$ainstanceofSuit;// true
?>

It also means that enum values are never<or>each other, since those comparisons are not meaningful on objects. Those comparisons will always returnfalsewhen working with enum values.

This type of case, with no related data, is called a "Pure Case." An Enum that contains only Pure Cases is called a Pure Enum.

All Pure Cases are implemented as instances of their enum type. The enum type is represented internally as a class.

All Cases have a read-only property,name, that is the case-sensitive name of the case itself.

<?php
printSuit::Spades->name;
// prints "Spades"
?>

It is also possible to use thedefined()andconstant()functions to check for the existence of or read an enum case if the name is obtained dynamically. This is, however, discouraged as usingBacked enumsshould work for most use cases.



Backed enumerations

By default, Enumerated Cases have no scalar equivalent. They are simply singleton objects. However, there are ample cases where an Enumerated Case needs to be able to round-trip to a database or similar datastore, so having a built-in scalar (and thus trivially serializable) equivalent defined intrinsically is useful.

To define a scalar equivalent for an Enumeration, the syntax is as follows:

<?php
enum Suit
:string
{
case
Hearts='H';
case
Diamonds='D';
case
Clubs='C';
case
Spades='S';
}
?>

A case that has a scalar equivalent is called a Backed Case, as it is "Backed" by a simpler value. An Enum that contains all Backed Cases is called a "Backed Enum." A Backed Enum may contain only Backed Cases. A Pure Enum may contain only Pure Cases.

A Backed Enum may be backed by types ofintorstring, and a given enumeration supports only a single type at a time (that is, no union ofint|string). If an enumeration is marked as having a scalar equivalent, then all cases must have a unique scalar equivalent defined explicitly. There are no auto-generated scalar equivalents (e.g., sequential integers). Backed cases must be unique; two backed enum cases may not have the same scalar equivalent. However, a constant may refer to a case, effectively creating an alias. SeeEnumeration constants.

Equivalent values must be literals or literal expressions. Constants and constant expressions are not supported. That is,1 + 1is allowed, but1 + SOME_CONSTis not.

Backed Cases have an additional read-only property,value, which is the value specified in the definition.

<?php
printSuit::Clubs->value;
// Prints "C"
?>

In order to enforce thevalueproperty as read-only, a variable cannot be assigned as a reference to it. That is, the following throws an error:

<?php
$suit
=Suit::Clubs;
$ref= &$suit->value;
// Error: Cannot acquire reference to property Suit::$value
?>

Backed enums implement an internalBackedEnuminterface, which exposes two additional methods:

  • from(int|string): selfwill take a scalar and return the corresponding Enum Case. If one is not found, it will throw aValueError. This is mainly useful in cases where the input scalar is trusted and a missing enum value should be considered an application-stopping error.
  • tryFrom(int|string): ?selfwill take a scalar and return the corresponding Enum Case. If one is not found, it will returnnull. This is mainly useful in cases where the input scalar is untrusted and the caller wants to implement their own error handling or default-value logic.

Thefrom()andtryFrom()methods follow standard weak/strong typing rules. In weak typing mode, passing an integer or string is acceptable and the system will coerce the value accordingly. Passing a float will also work and be coerced. In strict typing mode, passing an integer tofrom()on a string-backed enum (or vice versa) will result in aTypeError, as will a float in all circumstances. All other parameter types will throw a TypeError in both modes.

<?php
$record
=get_stuff_from_database($id);
print
$record['suit'];

$suit=Suit::from($record['suit']);
// Invalid data throws a ValueError: "X" is not a valid scalar value for enum "Suit"
print$suit->value;

$suit=Suit::tryFrom('A') ??Suit::Spades;
// Invalid data returns null, so Suit::Spades is used instead.
print$suit->value;
?>

Manually defining afrom()ortryFrom()method on a Backed Enum will result in a fatal error.



Enumeration methods

Enums (both Pure Enums and Backed Enums) may contain methods, and may implement interfaces. If an Enum implements an interface, then any type check for that interface will also accept all cases of that Enum.

<?php
interfaceColorful
{
public function
color():string;
}

enum SuitimplementsColorful
{
case
Hearts;
case
Diamonds;
case
Clubs;
case
Spades;

// Fulfills the interface contract.
public functioncolor():string
{
return
match($this) {
Suit::Hearts,Suit::Diamonds=>'Red',
Suit::Clubs,Suit::Spades=>'Black',
};
}

// Not part of an interface; that's fine.
public functionshape():string
{
return
"Rectangle";
}
}

function
paint(Colorful $c) { ... }

paint(Suit::Clubs);// Works

printSuit::Diamonds->shape();// prints "Rectangle"
?>

In this example, all four instances ofSuithave two methods,color()andshape(). As far as calling code and type checks are concerned, they behave exactly the same as any other object instance.

On a Backed Enum, the interface declaration goes after the backing type declaration.

<?php
interfaceColorful
{
public function
color():string;
}

enum Suit:stringimplementsColorful
{
case
Hearts='H';
case
Diamonds='D';
case
Clubs='C';
case
Spades='S';

// Fulfills the interface contract.
public functioncolor():string
{
return
match($this) {
Suit::Hearts,Suit::Diamonds=>'Red',
Suit::Clubs,Suit::Spades=>'Black',
};
}
}
?>

Inside a method, the$thisvariable is defined and refers to the Case instance.

Methods may be arbitrarily complex, but in practice will usually return a static value ormatchon$thisto provide different results for different cases.

Note that in this case it would be a better data modeling practice to also define aSuitColorEnum Type with values Red and Black and return that instead. However, that would complicate this example.

The above hierarchy is logically similar to the following class structure (although this is not the actual code that runs):

<?php
interfaceColorful
{
public function
color():string;
}

final class
SuitimplementsUnitEnum,Colorful
{
public const
Hearts= newself('Hearts');
public const
Diamonds= newself('Diamonds');
public const
Clubs= newself('Clubs');
public const
Spades= newself('Spades');

private function
__construct(publicreadonly string $name) {}

public function
color():string
{
return
match($this) {
Suit::Hearts,Suit::Diamonds=>'Red',
Suit::Clubs,Suit::Spades=>'Black',
};
}

public function
shape():string
{
return
"Rectangle";
}

public static function
cases(): array
{
// Illegal method, because manually defining a cases() method on an Enum is disallowed.
// See also "Value listing" section.
}
}
?>

Methods may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.



Enumeration static methods

Enumerations may also have static methods. The use for static methods on the enumeration itself is primarily for alternative constructors. E.g.:

<?php
enum Size
{
case
Small;
case
Medium;
case
Large;

public static function
fromLength(int $cm): static
{
return
match(true) {
$cm<50=> static::Small,
$cm<100=> static::Medium,
default => static::
Large,
};
}
}
?>

Static methods may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.



Enumeration constants

Enumerations may include constants, which may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.

An enum constant may refer to an enum case:

<?php
enum Size
{
case
Small;
case
Medium;
case
Large;

public const
Huge=self::Large;
}
?>


Traits

Enumerations may leverage traits, which will behave the same as on classes. The caveat is that traitsused in an enum must not contain properties. They may only include methods and static methods. A trait with properties will result in a fatal error.

<?php
interfaceColorful
{
public function
color():string;
}

trait
Rectangle
{
public function
shape():string{
return
"Rectangle";
}
}

enum SuitimplementsColorful
{
use
Rectangle;

case
Hearts;
case
Diamonds;
case
Clubs;
case
Spades;

public function
color():string
{
return
match($this) {
Suit::Hearts,Suit::Diamonds=>'Red',
Suit::Clubs,Suit::Spades=>'Black',
};
}
}
?>


Enum values in constant expressions

Because cases are represented as constants on the enum itself, they may be used as static values in most constant expressions: property defaults, static variable defaults, parameter defaults, global and class constant values. They may not be used in other enum case values, but normal constants may refer to an enum case.

However, implicit magic method calls such asArrayAccesson enums are not allowed in static or constant definitions as we cannot absolutely guarantee that the resulting value is deterministic or that the method invocation is free of side effects. Function calls, method calls, and property access continue to be invalid operations in constant expressions.

<?php
// This is an entirely legal Enum definition.
enum DirectionimplementsArrayAccess
{
case
Up;
case
Down;

public function
offsetGet($val) { ... }
public function
offsetExists($val) { ... }
public function
offsetSet($val) { throw newException(); }
public function
offsetUnset($val) { throw newException(); }
}

class
Foo
{
// This is allowed.
constBar=Direction::Down;

// This is disallowed, as it may not be deterministic.
constBar=Direction::Up['short'];
// Fatal error: Cannot use [] on enums in constant expression
}

// This is entirely legal, because it's not a constant expression.
$x=Direction::Up['short'];
?>


Differences from objects

Although Enums are built on classes and objects, they do not support all object-related functionality. In particular, Enum cases are forbidden from having state.

  • Constructors and Destructors are forbidden.
  • Inheritance is not supported. Enums may not extend or be extended.
  • Static or object properties are not allowed.
  • Cloning an Enum case is not supported, as cases must be singleton instances.
  • Magic methods, except for those listed below, are disallowed.
  • Enums must always be declared before they are used.

The following object functionality is available, and behaves just as it does on any other object:

  • Public, private, and protected methods.
  • Public, private, and protected static methods.
  • Public, private, and protected constants.
  • Enums may implement any number of interfaces.
  • Enums and cases may haveattributesattached to them. TheTARGET_CLASStarget filter includes Enums themselves. TheTARGET_CLASS_CONSTtarget filter includes Enum Cases.
  • __call,__callStatic, and__invokemagic methods
  • __CLASS__and__FUNCTION__constants behave as normal

The::classmagic constant on an Enum type evaluates to the type name including any namespace, exactly the same as an object. The::classmagic constant on a Case instance also evaluates to the Enum type, as it is an instance of that type.

Additionally, enum cases may not be instantiated directly withnew, nor withReflectionClass::newInstanceWithoutConstructor()in reflection. Both will result in an error.

<?php
$clovers
= newSuit();
// Error: Cannot instantiate enum Suit
$horseshoes= (newReflectionClass(Suit::class))->newInstanceWithoutConstructor()
// Error: Cannot instantiate enum Suit
?>


Value listing

Both Pure Enums and Backed Enums implement an internal interface namedUnitEnum.UnitEnumincludes a static methodcases().cases()returns a packed array of all defined Cases in the order of declaration.

<?php
Suit
::cases();
// Produces: [Suit::Hearts, Suit::Diamonds, Suit::Clubs, Suit::Spades]
?>

Manually defining acases()method on an Enum will result in a fatal error.



Serialization

Enumerations are serialized differently from objects. Specifically, they have a new serialization code,"E", that specifies the name of the enum case. The deserialization routine is then able to use that to set a variable to the existing singleton value. That ensures that:

<?php
Suit
::Hearts===unserialize(serialize(Suit::Hearts));

print
serialize(Suit::Hearts);
// E:11:"Suit:Hearts";
?>

On deserialization, if an enum and case cannot be found to match a serialized value a warning will be issued andfalsereturned.

If a Pure Enum is serialized to JSON, an error will be thrown. If a Backed Enum is serialized to JSON, it will be represented by its value scalar only, in the appropriate type. The behavior of both may be overridden by implementingJsonSerializable.

Forprint_r(), the output of an enum case is slightly different from objects to minimize confusion.

<?php
enum Foo
{
case
Bar;
}

enum Baz:int{
case
Beep=5;
}

print_r(Foo::Bar);
print_r(Baz::Beep);

/* Produces

Foo Enum (
[name] => Bar
)
Baz Enum:int {
[name] => Beep
[value] => 5
}
*/
?>


Why enums aren't extendable

Classes have contracts on their methods:

<?php

classA{}
class
BextendsA{}

function
foo(A $a) {}

function
bar(B $b) {
foo($b);
}
?>

This code is type-safe, as B follows the contract of A, and through the magic of co/contra-variance, any expectation one may have of the methods will be preserved, exceptions excepted.

Enums have contracts on their cases, not methods:

<?php
enum ErrorCode
{
case
SOMETHING_BROKE;
}

function
quux(ErrorCode $errorCode)
{
// When written, this code appears to cover all cases
match($errorCode) {
ErrorCode::SOMETHING_BROKE=>true,
}
}

?>

Thematchstatement in the functionquuxcan be static analyzed to cover all of the cases in ErrorCode.

But imagine it was allowed to extend enums:

<?php
// Thought experiment code where enums are not final.
// Note, this won't actually work in PHP.
enum MoreErrorCodeextendsErrorCode{
case
PEBKAC;
}

function
fot(MoreErrorCode $errorCode) {
quux($errorCode);
}

fot(MoreErrorCode::PEBKAC);

?>

Under normal inheritance rules, a class that extends another will pass the type check.

The problem would be that thematchstatement inquux()no longer covers all the cases. Because it doesn't know aboutMoreErrorCode::PEBKACthe match will throw an exception.

Because of this enums are final and can't be extended.



Ejemplos

Ejemplo #1 Basic limited values

<?php
enum SortOrder
{
case
Asc;
case
Desc;
}

function
query($fields,$filter,SortOrder $order=SortOrder::Asc) { ... }
?>

Thequery()function can now proceed safe in the knowledge that$orderis guaranteed to be eitherSortOrder::AscorSortOrder::Desc. Any other value would have resulted in aTypeError, so no further error checking or testing is needed.

Ejemplo #2 Advanced exclusive values

<?php
enum UserStatus
:string
{
case
Pending='P';
case
Active='A';
case
Suspended='S';
case
CanceledByUser='C';

public function
label():string
{
return
match($this) {
static::
Pending=>'Pending',
static::
Active=>'Active',
static::
Suspended=>'Suspended',
static::
CanceledByUser=>'Canceled by user',
};
}
}
?>

In this example, a user's status may be one of, and exclusively,UserStatus::Pending,UserStatus::Active,UserStatus::Suspended, orUserStatus::CanceledByUser. A function can type a parameter againstUserStatusand then only accept those four values, period.

All four values have alabel()method, which returns a human-readable string. That string is independent of the "machine name" scalar equivalent string, which can be used in, for example, a database field or an HTML select box.

<?php
foreach (UserStatus::cases() as$case) {
printf('<option value="%s">%s</option>\n',$case->value,$case->label());
}
?>




Errores

Tabla de contenidos

Introducción

Desarfortunadamente, no importa lo cuidadoso que uno sea escribiendo código; los errores son un hecho de la vida. PHP notificará errores, advertencias y avisos para muchos problemas comunes de codificación y de tiempo de ejecución, por lo que saber cómo detectar y manejar estos errores hará la depuración mucho más sencilla.


Lo básico

PHP notifica errores en respuesta a varias condiciones de error internas. Estas se pueden utilizar para señalar varias condiciones diferentes, mostrándose y/o registrándose si fuera necesario.

Cada error que genera PHP incluye un tipo. Existe unalista de dichos tipos, junto con una breve descripción de su comportamiento y sus posibles causas.

Manejo de errores con PHP

Si no se establece un manejador de errores, PHP manejará cada error que ocurra según su configuración. Los errores que se notifican y los que se ignoran se controla mediante la directivaerror_reportingde php.ini, o durante la ejecución llamando aerror_reporting(). Sin embargo, se recomienda encarecidamente establecer la directiva de configuración, ya que algunos errores pueden ocurrir antes de comenzar la ejecución de un script.

En un entorno de desarrollo debería establecerse siempreerror_reportingaE_ALL, debido a que es necesario reconocer y corregir los problemas generados por PHP. En producción, se podría establecer esta directiva a un nivel de menor verbosidad comoE_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED, aunque en muchos casosE_ALLtambién es apropiado, ya que puede proporcionar advertencias precoces de problemas potenciales.

Lo que PHP hace con estos errores depende de dos directivas más de php.ini.display_errorscontrola si el error es mostrado como parte de la salida del script. Esta debería estar siempre deshabilitada en un entorno de producción, ya que puede incluir información confidencial tal como contraseñas de bases de datos, aunque a menudo es útil habilitarla en desarrollo debido a que asegura la notificación inmediata de problemas.

Además de mostrar errores, PHP puede registrarlos cuando la directivalog_errorsestá habilitada. Esta registrará cualquier error en el fichero o registro del sistema definido porerror_log. Esta directiva puede ser extremadamente útil en un entorno de producción debido a que se pueden registrar los errores que ocurran y generar informes basados en ellos.

Manejadores de errores de usuario

Si el manejo de errores predeterminado de PHP es inadecuado, también se pueden manejar muchos tipos de error con un manejador de errores propio medianteset_error_handler(). Mientras que algunos tipos de error no se pueden manejar de esta forma, aquellos que sí se pueden lo hacen de la manera en que su script vea apropiada: por ejemplo, se puede emplear para mostrar al usuario una página de error personalizada y luego notificar más directamente mediante un registro, tal como el envío de un correo electrónico.



Errores en PHP 7

PHP 7 cambia la mayoría de los errores notificados por PHP. En lugar de notificar errores a través del mecanismo de notificación de errores tradicional de PHP 5, la mayoría de los errores ahora son notificados lanzando excepcionesError.

Al igual que las excepciones normales, las excepcionesErrorse propagarán hasta alcanzar el primer bloquecatchcoincidente. Si no hay bloques coincidentes, será invocado cualquier manejador de excepciones predeterminado instalado conset_exception_handler(), y si no hubiera ningún manejador de excepciones predeterminado, la excepción será convertida en un error fatal y será manejada como un error tradicional.

Debido a que la jerarquía deErrorno hereda deException, el código que emplee bloquescatch (Exception $e) { ... }para manejar excepciones no capturadas en PHP 5 encontrará que estosErrores no son capturados por dichos bloques. Se requiere, por tanto, un bloquecatch (Error $e) { ... }o un manejadorset_exception_handler().




Excepciones

Tabla de contenidos


Ampliar las Excepciones

Una clase de Excepción definida por el usuario puede ser definida ampliando la clase Exception interna. Los miembros y las propiedades de abajo muestran lo que es accesible dentro de la clase hija que deriva de la clase Exception interna.

Ejemplo #1 La clase Exception Interna

<?php
classException
{
protected
$message='Unknown exception';// mensaje de excepción
private$string;// caché de __toString
protected$code=0;// código de excepción definido por el usuario
protected$file;// nombre de archivo fuente de la excepción
protected$line;// línea fuente de la excepción
private$trace;// determinación del origen
private$previous;// excepción previa si la excepción está anidada

public function__construct($message=null,$code=0,Exception $previous=null);

final private function
__clone();// Inhibe la clonación de excepciones.

final public functiongetMessage();// mensaje de excepción
final public functiongetCode();// código de excepción
final public functiongetFile();// nombre de archivo fuente
final public functiongetLine();// línea fuente
final public functiongetTrace();// un array de backtrace()
final public functiongetPrevious();// excepción anterior
final public functiongetTraceAsString();// string formateado del seguimiento del origen

// Sobrescribible
public function__toString();// string formateado para mostrar
}
?>

Si una clase extiende la clase Exception interna y redefine elconstructor, se recomienda encarecidamente que también llame aparent::__construct()para asegurarse que toda la información disponible haya sido asignada apropiadamente. El método__toString()puede ser sobrescrito para proporcionar una salida personalizada cuando el objeto es presentado como un string.

Nota:

Las excepciones no se pueden clonar. Intentarclonaruna Excepción resultará en un errorE_ERRORfatal.

Ejemplo #2 Extender la clase Exception (PHP 5.3.0+)

<?php
/**
* Definir una clase de excepción personalizada
*/
classMiExcepciónextendsException
{
// Redefinir la excepción, por lo que el mensaje no es opcional
public function__construct($message,$code=0,Exception $previous=null) {
// algo de código

// asegúrese de que todo está asignado apropiadamente
parent::__construct($message,$code,$previous);
}

// representación de cadena personalizada del objeto
public function__toString() {
return
__CLASS__.": [{$this->code}]:{$this->message}\n";
}

public function
funciónPersonalizada() {
echo
"Una función personalizada para este tipo de excepción\n";
}
}


/**
* Crear una clase para probar la excepción
*/
classProbarExcepción
{
public
$var;

const
THROW_NONE=0;
const
THROW_CUSTOM=1;
const
THROW_DEFAULT=2;

function
__construct($avalue=self::THROW_NONE) {

switch (
$avalue) {
case
self::THROW_CUSTOM:
// lanzar la excepción personalizada
throw newMiExcepción('1 no es un parámetro válido',5);
break;

case
self::THROW_DEFAULT:
// lanzar la predeterminada.
throw newException('2 no está permitido como parámetro',6);
break;

default:
// No hay excepción, el objeto se creará.
$this->var=$avalue;
break;
}
}
}


// Ejemplo 1
try {
$o= newProbarExcepción(ProbarExcepción::THROW_CUSTOM);
} catch (
MiExcepción $e) {// Será atrapada
echo"Atrapada mi excepción\n",$e;
$e->funciónPersonalizada();
} catch (
Exception $e) {// Skipped
echo"Atrapada la Excepción Predeterminada\n",$e;
}

// Continuar la ejecución
var_dump($o);// Null
echo"\n\n";


// Ejemplo 2
try {
$o= newProbarExcepción(ProbarExcepción::THROW_DEFAULT);
} catch (
MiExcepción $e) {// Este tipo no coincide
echo"Atrapada mi excepción\n",$e;
$e->funciónPersonalizada();
} catch (
Exception $e) {// Will be caught
echo"Atrapada la Excepción Predeterminada\n",$e;
}

// Continuar la ejecución
var_dump($o);// Null
echo"\n\n";


// Ejemplo 3
try {
$o= newProbarExcepción(ProbarExcepción::THROW_CUSTOM);
} catch (
Exception $e) {// Será atrapada
echo"Atrapada la Excepción Predeterminada\n",$e;
}

// Continuar la ejecución
var_dump($o);// Null
echo"\n\n";


// Ejemplo 4
try {
$o= newProbarExcepción();
} catch (
Exception $e) {// Saltado, sin excepción
echo"Atrapada la Excepción Predeterminada\n",$e;
}

// Continuar la ejecución
var_dump($o);// ProbarExcepción
echo"\n\n";
?>

Nota:

Las versiones de PHP 5, anteriores a PHP 5.3.0, no soportan excepciones anidadas. El siguiente fragmento de código se puede usar para reemplazar la clase MiExcepción si se desea ejecutar este ejemplo.

<?php
/**
* Definir una clase de excepción personalizada
*/
classMiExcepciónextendsException
{
// Redefinir la excepción, por lo que el mensaje no es opcional
public function__construct($message,$code=0) {
// algo de código

// asegúrese de que todo está asignador apropiadamente
parent::__construct($message,$code);
}

// representación de cadena personalizada del objeto
public function__toString() {
return
__CLASS__.": [{$this->code}]:{$this->message}\n";
}

public function
funciónPersonalizada() {
echo
"Una función personalizada para este tipo de excepción\n";
}
}
?>


PHP 5 tiene un modelo de excepciones similar al de otros lenguajes de programación. Una excepción puede ser lanzada ("thrown"), y atrapada ("catched") dentro de PHP. El código puede estar dentro de un bloquetrypara facilitar la captura de excepciones potenciales. Cada bloquetrydebe tener al menos un bloquecatchofinallycorrespondiente.

El objeto lanzado debe ser una instancia de la claseExceptiono una subclase deException. Intentar lanzar un objeto que no lo sea resultará en un Error Fatal de PHP.

catch

Se pueden usar múltiples bloquescatchpara atrapar diferentes clases de excepciones. La ejecución normal (cuando no es lanzada ninguna excepción dentro del bloquetry) continuará después del último bloquecatchdefinido en la sencuencia. Las excepciones pueden ser lanzadas ("thrown") (o relanzadas) dentro de un bloquecatch.

Cuando una excepción es lanzada, el código siguiente a la declaración no será ejecutado, y PHP intentará encontrar el primer bloquecatchcoincidente. Si una excepción no es capturada, se emitirá un Error Fatal de PHP con un mensaje "Uncaught Exception ..." ("Excepción No Capturada"), a menos que se haya definido un manejador conset_exception_handler().

finally

En PHP 5.5 y posterior, se puede utilizar un bloquefinallydespués o en lugar de los bloquescatch. El código de dentro del bloquefinallysiempre se ejecutará después de los bloquestryycatch, independientemente de que se haya lanzado una excepción o no, y antes de que la ejecución normal continúe.

Notas

Nota:

Las funciones internas de PHP utilizan principalmente laInformación de Errores, sólo las extensionesOrientadas a objetosmodernas utilizan excepciones. Sin embargo, los errores se pueden traducir a excepciones simplemente conErrorException.

Sugerencia

LaBiblioteca Estádar de PHP (SPL)proporciona un buen número deexcepciones internas.

Ejemplos

Ejemplo #3 Lanzar una Excepción

<?php
functioninverso($x) {
if (!
$x) {
throw new
Exception('División por cero.');
}
return
1/$x;
}

try {
echo
inverso(5) ."\n";
echo
inverso(0) ."\n";
} catch (
Exception $e) {
echo
'Excepción capturada: ',$e->getMessage(),"\n";
}

// Continuar la ejecución
echo'Hola Mundo\n';
?>

El resultado del ejemplo sería:

0.2
Excepción capturada: División por cero.
Hola Mundo

Ejemplo #4 Manejo de excepciones con un bloquefinally

<?php
functioninverse($x) {
if (!
$x) {
throw new
Exception('División por cero.');
}
return
1/$x;
}

try {
echo
inverse(5) ."\n";
} catch (
Exception $e) {
echo
'Excepción capturada: ',$e->getMessage(),"\n";
} finally {
echo
"Primer finally.\n";
}

try {
echo
inverse(0) ."\n";
} catch (
Exception $e) {
echo
'Excepción capturada: ',$e->getMessage(),"\n";
} finally {
echo
"Segundo finally.\n";
}

// Continuar ejecución
echo'Hola Mundo\n';
?>

El resultado del ejemplo sería:

0.2
Primer finally.
Excepción capturada: División por cero.
Segundo finally.
Hola Mundo

Ejemplo #5 Excepciones anidadas

<?php

classMiExcepciónextendsException{ }

class
Prueba{
public function
probar() {
try {
try {
throw new
MiExcepción('foo!');
} catch (
MiExcepción $e) {
// relanzarla
throw$e;
}
} catch (
Exception $e) {
var_dump($e->getMessage());
}
}
}

$foo= newPrueba;
$foo->probar();

?>

El resultado del ejemplo sería:

string(4) "foo!"


Fibers

Fibers overview

(PHP 8 >= 8.1.0)

Fibers represent full-stack, interruptible functions. Fibers may be suspended from anywhere in the call-stack, pausing execution within the fiber until the fiber is resumed at a later time.

Fibers pause the entire execution stack, so the direct caller of the function does not need to change how it invokes the function.

Execution may be interrupted anywhere in the call stack usingFiber::suspend()(that is, the call toFiber::suspend()may be in a deeply nested function or not even exist at all).

Unlike stack-lessGenerators, eachFiberhas its own call stack, allowing them to be paused within deeply nested function calls. A function declaring an interruption point (that is, callingFiber::suspend()) need not change its return type, unlike a function usingyieldwhich must return aGeneratorinstance.

Fibers can be suspended in any function call, including those called from within the PHP VM, such as functions provided toarray_map()or methods called byforeachon anIteratorobject.

Once suspended, execution of the fiber may be resumed with any value usingFiber::resume()or by throwing an exception into the fiber usingFiber::throw(). The value is returned (or exception thrown) fromFiber::suspend().

Nota:Due to current limitations it is not possible to switch fibers in the destructor of an object.

Ejemplo #1 Basic usage

<?php
$fiber
= newFiber(function ():void{
$value=Fiber::suspend('fiber');
echo
"Value used to resume fiber: ",$value,PHP_EOL;
});

$value=$fiber->start();

echo
"Value from fiber suspending: ",$value,PHP_EOL;

$fiber->resume('test');
?>

El resultado del ejemplo sería:

Value from fiber suspending: fiber
Value used to resume fiber: test


Generadores

Tabla de contenidos


Información general de los generadores

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Los generadores proporcionan un modo fácil de implementariteradoressimples sin la sobrecarga o complejidad de implementar una clase que implemente la interfazIterator.

Un generador permite escribir código que utiliceforeachpara iterar sobre un conjunto de datos sin que sea necesario cargar el array en memoria, lo que puede ocasionar que se exceda el límite de memoria, o requiera una cantidad considerable de tiempo de procesado para generarse. En su lugar, se puede escribir una función generadora, que es igual que unafunciónnormal, con la salvedad de que en vez de hacer un soloreturn, un generador puede invocaryieldtantas veces como necesite para proporcionar valores por los que iterar.

Un ejemplo simple de esto es reimplementar la funciónrange()como un generador. La función estándarrange()tiene que generar un array con cada uno de los valores y devolverlo, lo que puede resultar en arrays grandes: por ejemplo, llamarrange(0, 1000000)resultará en más de 100 MB de memoria utilizada.

Como alternativa, se puede implementar un generadorxrange(), que sólo necesitará memoria para crear un objetoIteratory controlar el estado actual del generador de manera interna, lo que no ocupa más de 1 kilobyte.

Ejemplo #1 Implementandorange()como generador

<?php
functionxrange($start,$limit,$step=1) {
if (
$start<$limit) {
if (
$step<=0) {
throw new
LogicException('Step tiene que ser +ve');
}

for (
$i=$start;$i<=$limit;$i+=$step) {
yield
$i;
}
} else {
if (
$step>=0) {
throw new
LogicException('Step tiene que ser -ve');
}

for (
$i=$start;$i>=$limit;$i+=$step) {
yield
$i;
}
}
}

/*
* Obsereve que tanto range() como xrange() producen la misma
* salida a continuación.
*/

echo'Números impares de una cifra de range(): ';
foreach (
range(1,9,2) as$number) {
echo
"$number";
}
echo
"\n";

echo
'Números impares de una cifra de xrange(): ';
foreach (
xrange(1,9,2) as$number) {
echo
"$number";
}
?>

El resultado del ejemplo sería:

Números impares de una cifra de range():  1 3 5 7 9 
Números impares de una cifra de xrange(): 1 3 5 7 9 

ObjetosGenerator

Cuando una función generadora es invocada por primera vez, se devuelve un objeto de la clase internaGenerator. Este objeto implementa la interfazIteratorde la misma forma que lo haría un objeto iterador de solo avance, y proporciona métodos que pueden ser invocados para manipular el estado del generador, incluyendo el envío de valores hacia y la devolución de valores desde él.



Generator syntax

Una función generadora es igual que una función normal, con la diferencia de que en vez de devolver un valor, un generador invocayieldtantas veces como necesita.

Cuando se llama a una función generadora, devuelve un objeto que puede ser iterado. Cuando se itera sobre ese objeto (por ejemplo, con un bucleforeach), PHP llamará a la función generadora cada vez que necesite un valor, y guardará el estado del generador cuando este provea un valor con yield para que ese estado pueda ser recuperado cuando el próximo valor sea requerido.

Cuando no hay más valores que se puedan proporcionar, la función generadora puede simplemente terminar, y el código desde el que se la llama continuará como si un array se hubiera quedado sin valores.

Nota:

Un generador no puede retornar un valor: hacerlo resultaría en un error de compilación. Unreturnvacío es válido en cuanto a sintaxis dentro de un generador y terminará el generador.

yieldkeyword

La clave de una función generadora es la palabra reservadayield. En su forma más simple, la sentencia yield es parecida a la sentencia return, excepto en que en vez de detener la ejecución de la función y devolver un valor, yield facilita el valor al bucle que itera sobre el generador y pausa la ejecución de la función generadora.

Ejemplo #1 Ejemplo sencillo de facilitar valores con yield

<?php
functiongen_one_to_three() {
for (
$i=1;$i<=3;$i++) {
// Observe que $i es preservado entre yields
yield$i;
}
}

$generator=gen_one_to_three();
foreach (
$generatoras$value) {
echo
"$value\n";
}
?>

El resultado del ejemplo sería:

1
2
3

Nota:

Internamente, las claves enteras secuenciales serán asociadas con los valores sobre los que se usa yield, como un array no asociativo.

Precaución

Si se utiliza yield en el contexto de una expresión (por ejemplo, en el lado derecho de una asignación), se debe poner la sentencia yield entre paréntesis en PHP 5. Por ejemplo, esto es válido:

$data = (yield $value);

Pero esto no lo es, y resultará en un error de análisis en PHP 5:

$data = yield $value;

Las restricciones parentéticas no se aplican en PHP 7.

Esta sintaxis podría usarse junto con el métodoGenerator::send().

Utilizar yield para facilitar valores con claves

PHP soporta arrays asociativos, y los generadores no son menos. Además de facilitar valores simples, como se muestra arriba, también se puede facilitar una clave al mismo tiempo.

La sintaxis para facilitar un par clave-valor es muy similar a la utilizada para definir un array asociativo, como se muestra a continuación.

Ejemplo #2 Facilitar un par clave-valor

<?php
/*
* La entrada son campos separados por punto y coma, con el primer
* campo siendo la ID utilizada como clave.
*/

$input= <<<'EOF'
1;PHP;Likes dollar signs
2;Python;Likes whitespace
3;Ruby;Likes blocks
EOF;

function
input_parser($input) {
foreach (
explode("\n",$input) as$line) {
$fields=explode(';',$line);
$id=array_shift($fields);

yield
$id=>$fields;
}
}

foreach (
input_parser($input) as$id=>$fields) {
echo
"$id:\n";
echo
"$fields[0]\n";
echo
"$fields[1]\n";
}
?>

El resultado del ejemplo sería:

1:
    PHP
    Likes dollar signs
2:
    Python
    Likes whitespace
3:
    Ruby
    Likes blocks
Precaución

Como en el ejemplo anterior, facilitar un par clave-valor en contexto de expresión requiere que la sentencia yield sea puesta entre paréntesis:

$data = (yield $key => $value);

Facilitar valores nulos

Yield puede ser invocado sin argumentos para facilitar un valornullcon una clave automática.

Ejemplo #3 Yieldingnulls

<?php
functiongen_three_nulls() {
foreach (
range(1,3) as$i) {
yield;
}
}

var_dump(iterator_to_array(gen_three_nulls()));
?>

El resultado del ejemplo sería:

array(3) {
  [0]=>
  NULL
  [1]=>
  NULL
  [2]=>
  NULL
}

Facilitar por referencia

Las funciones generadoras son capaces de facilitar valores por referencia igual que lo hacen por valor. Esto se hace de la misma forma quedevolviendo referencias desde funciones: poniendo un ampersand (signo &) delante del nombre de la función.

Ejemplo #4 Facilitar valores por referencia

<?php
function &gen_reference() {
$value=3;

while (
$value>0) {
yield
$value;
}
}

/*
* Observe que es posible cambiar $number desde dentro del bucle, y
* dado que el generador está facilitando referencias, $value
* dentro de gen_reference() cambia.
*/
foreach (gen_reference() as &$number) {
echo (--
$number).'... ';
}
?>

El resultado del ejemplo sería:

2... 1... 0... 

Delegación de generadores medianteyield from

En PHP 7, la delegación de generadores permite producir valores desde otro generador, objetoTraversable, oarraymediante la palabra reservadayield from. El generador externo producirá entonces todos los valores desde el generador interno, object, o array hasta que este ya no sea válido, después de lo cual la ejecuión continuará en el generador externo.

Si un generador se emplea conyield from, la expresiónyield fromtambién devolverá cualquier valor devuelto por el generador interno.

Precaución

Almacenamiento en un array (p.ej. coniterator_to_array())

yield fromno reinicia las claves. Preserva las claves devueltas por el objetoTraversableoarray. Por tanto, algunos valores podrían compartir una clave en común con otroyieldoyield from, los cuales, en el momento de la inserción en el array, sobrescribirán los valores antiguos con esa clave.

Un caso común donde esto importa es cuandoiterator_to_array()devuelve un array con claves por defecto, conduciendo a posibles resultados inesperados.iterator_to_array()tiene un segundo parámetro,use_keys, que puede ser establecido afalsepara recoger todos los valores mientras ignora las claves devueltas por elGenerator.

Ejemplo #5yield fromconiterator_to_array()

<?php
functionfrom() {
yield
1;// clave 0
yield2;// clave 1
yield3;// clave 2
}
function
gen() {
yield
0;// clave 0
yield fromfrom();// claves 0-2
yield4;// clave 1
}
// pasar false como segundo parámetro para obtener un array [0, 1, 2, 3, 4]
var_dump(iterator_to_array(gen()));
?>

El resultado del ejemplo sería:

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(4)
  [2]=>
  int(3)
}

Ejemplo #6 Uso básico deyield from

<?php
functioncontar_hasta_diez() {
yield
1;
yield
2;
yield from [
3,4];
yield from new
ArrayIterator([5,6]);
yield from
siete_ocho();
yield
9;
yield
10;
}

function
siete_ocho() {
yield
7;
yield from
ocho();
}

function
ocho() {
yield
8;
}

foreach (
contar_hasta_diez() as$num) {
echo
"$num";
}
?>

El resultado del ejemplo sería:

1 2 3 4 5 6 7 8 9 10 

Ejemplo #7yield fromy valores devueltos

<?php
functioncontar_hasta_diez() {
yield
1;
yield
2;
yield from [
3,4];
yield from new
ArrayIterator([5,6]);
yield from
siete_ocho();
return yield from
nueve_diez();
}

function
siete_ocho() {
yield
7;
yield from
ocho();
}

function
ocho() {
yield
8;
}

function
nueve_diez() {
yield
9;
return
10;
}

$gen=contar_hasta_diez();
foreach (
$genas$num) {
echo
"$num";
}
echo
$gen->getReturn();
?>

El resultado del ejemplo sería:

1 2 3 4 5 6 7 8 9 10


Comparación entre generadores y objetosIterator

La principal ventaja de los generadores es su simplicadad. Se ha de escribir mucho menos código repetitivo en comparación con el necesario para implementar una claseIterator, y el código es generalmente mucho más legible. Por ejemplo, la siguiente función y clase son equivalentes:

<?php
functiongetLinesFromFile($fileName) {
if (!
$fileHandle=fopen($fileName,'r')) {
return;
}

while (
false!==$line=fgets($fileHandle)) {
yield
$line;
}

fclose($fileHandle);
}

// Contra...

classLineIteratorimplementsIterator{
protected
$fileHandle;

protected
$line;
protected
$i;

public function
__construct($fileName) {
if (!
$this->fileHandle=fopen($fileName,'r')) {
throw new
RuntimeException('Couldn\'t open file "'.$fileName.'"');
}
}

public function
rewind() {
fseek($this->fileHandle,0);
$this->line=fgets($this->fileHandle);
$this->i=0;
}

public function
valid() {
return
false!==$this->line;
}

public function
current() {
return
$this->line;
}

public function
key() {
return
$this->i;
}

public function
next() {
if (
false!==$this->line) {
$this->line=fgets($this->fileHandle);
$this->i++;
}
}

public function
__destruct() {
fclose($this->fileHandle);
}
}
?>

La flexibilidad, sin embargo, tiene un coste: los generadores son iteradores unidireccionales, ya que no pueden ser rebobinados una vez la iteración ha empezado. Esto también significa que se puede iterar sobre el mismo generador varias veces: el generador necesitará ser reconstruido llamando a la función generadora de nuevo.




Attributes

Tabla de contenidos


Attributes overview

(PHP 8)

Attributes offer the ability to add structured, machine-readable metadata information on declarations in code: Classes, methods, functions, parameters, properties and class constants can be the target of an attribute. The metadata defined by attributes can then be inspected at runtime using theReflection APIs. Attributes could therefore be thought of as a configuration language embedded directly into code.

With attributes the generic implementation of a feature and its concrete use in an application can be decoupled. In a way it is comparable to interfaces and their implementations. But where interfaces and implementations are about code, attributes are about annotating extra information and configuration. Interfaces can be implemented by classes, yet attributes can also be declared on methods, functions, parameters, properties and class constants. As such they are more flexible than interfaces.

A simple example of attribute usage is to convert an interface that has optional methods to use attributes. Let's assume anActionHandlerinterface representing an operation in an application, where some implementations of an action handler require setup and others do not. Instead of requiring all classes that implementActionHandlerto implement a methodsetUp(), an attribute can be used. One benefit of this approach is that we can use the attribute several times.

Ejemplo #1 Implementing optional methods of an interface with Attributes

<?php
interfaceActionHandler
{
public function
execute();
}

#[Attribute]
classSetUp{}

class
CopyFileimplementsActionHandler
{
public
string $fileName;
public
string $targetDirectory;

#[SetUp]
public functionfileExists()
{
if (!
file_exists($this->fileName)) {
throw new
RuntimeException("File does not exist");
}
}

#[SetUp]
public functiontargetDirectoryExists()
{
if (!
file_exists($this->targetDirectory)) {
mkdir($this->targetDirectory);
} elseif (!
is_dir($this->targetDirectory)) {
throw new
RuntimeException("Target directory$this->targetDirectoryis not a directory");
}
}

public function
execute()
{
copy($this->fileName,$this->targetDirectory.'/'.basename($this->fileName));
}
}

function
executeAction(ActionHandler $actionHandler)
{
$reflection= newReflectionObject($actionHandler);

foreach (
$reflection->getMethods() as$method) {
$attributes=$method->getAttributes(SetUp::class);

if (
count($attributes) >0) {
$methodName=$method->getName();

$actionHandler->$methodName();
}
}

$actionHandler->execute();
}

$copyAction= newCopyFile();
$copyAction->fileName="/tmp/foo.jpg";
$copyAction->targetDirectory="/home/user";

executeAction($copyAction);


Attribute syntax

There are several parts to the attributes syntax. First, an attribute declaration is always enclosed with a starting#[and a corresponding ending]. Inside, one or many attributes are listed, separated by comma. The attribute name is an unqualified, qualified or fully-qualified name as described inUsing Namespaces Basics. Arguments to the attribute are optional, but are enclosed in the usual parenthesis(). Arguments to attributes can only be literal values or constant expressions. Both positional and named arguments syntax can be used.

Attribute names and their arguments are resolved to a class and the arguments are passed to its constructor, when an instance of the attribute is requested through the Reflection API. As such a class should be introduced for each attribute.

Ejemplo #1 Attribute Syntax

<?php
// a.php
namespaceMyExample;

use
Attribute;

#[Attribute]
classMyAttribute
{
const
VALUE='value';

private
$value;

public function
__construct($value=null)
{
$this->value=$value;
}
}

// b.php

namespaceAnother;

use
MyExample\MyAttribute;

#[MyAttribute]
#[\MyExample\MyAttribute]
#[MyAttribute(1234)]
#[MyAttribute(value: 1234)]
#[MyAttribute(MyAttribute::VALUE)]
#[MyAttribute(array("key" => "value"))]
#[MyAttribute(100 + 200)]
classThing
{
}

#[MyAttribute(1234), MyAttribute(5678)]
classAnotherThing
{
}


Reading Attributes with the Reflection API

To access attributes from classes, methods, functions, parameters, properties and class constants, the Reflection API provides the methodgetAttributes()on each of the corresponding Reflection objects. This method returns an array ofReflectionAttributeinstances that can be queried for attribute name, arguments and to instantiate an instance of the represented attribute.

This separation of reflected attribute representation from actual instance increases control of the programmer to handle errors regarding missing attribute classes, mistyped or missing arguments. Only after callingReflectionAttribute::newInstance(), objects of the attribute class are instantiated and the correct matching of arguments is validated, not earlier.

Ejemplo #1 Reading Attributes using Reflection API

<?php

#[Attribute]
classMyAttribute
{
public
$value;

public function
__construct($value)
{
$this->value=$value;
}
}

#[MyAttribute(value: 1234)]
classThing
{
}

function
dumpAttributeData($reflection) {
$attributes=$reflection->getAttributes();

foreach (
$attributesas$attribute) {
var_dump($attribute->getName());
var_dump($attribute->getArguments());
var_dump($attribute->newInstance());
}
}

dumpAttributeData(newReflectionClass(Thing::class));
/*
string(11) "MyAttribute"
array(1) {
["value"]=>
int(1234)
}
object(MyAttribute)#3 (1) {
["value"]=>
int(1234)
}
*/

Instead of iterating all attributes on the reflection instance, only those of a particular attribute class can be retrieved by passing the searched attribute class name as argument.

Ejemplo #2 Reading Specific Attributes using Reflection API

<?php

functiondumpMyAttributeData($reflection) {
$attributes=$reflection->getAttributes(MyAttribute::class);

foreach (
$attributesas$attribute) {
var_dump($attribute->getName());
var_dump($attribute->getArguments());
var_dump($attribute->newInstance());
}
}

dumpMyAttributeData(newReflectionClass(Thing::class));


Declaring Attribute Classes

While not strictly required it is recommended to create an actual class for every attribute. In the most simple case only an empty class is needed with the#[Attribute]attribute declared that can be imported from the global namespace with a use statement.

Ejemplo #1 Simple Attribute Class

<?php

namespaceExample;

use
Attribute;

#[Attribute]
classMyAttribute
{
}

To restrict the type of declaration an attribute can be assigned to, a bitmask can be passed as the first argument to the#[Attribute]declaration.

Ejemplo #2 Using target specification to restrict where attributes can be used

<?php

namespaceExample;

use
Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
classMyAttribute
{
}

DeclaringMyAttributeon another type will now throw an exception during the call toReflectionAttribute::newInstance()

The following targets can be specified:

  • Attribute::TARGET_CLASS
  • Attribute::TARGET_FUNCTION
  • Attribute::TARGET_METHOD
  • Attribute::TARGET_PROPERTY
  • Attribute::TARGET_CLASS_CONSTANT
  • Attribute::TARGET_PARAMETER
  • Attribute::TARGET_ALL

By default an attribute can only be used once per declaration. If the attribute should be repeatable on declarations it must be specified as part of the bitmask to the#[Attribute]declaration.

Ejemplo #3 Using IS_REPEATABLE to allow attribute on a declaration multiple times

<?php

namespaceExample;

use
Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
classMyAttribute
{
}



Explicación de las Referencias

Tabla de contenidos


¿Qué son las Referencias?

Las Referencias en PHP son medios de acceder al mismo contenido de una variable mediante diferentes nombres. No son como los punteros de C; por ejemplo, no se puede realizar aritmética de punteros con ellas, realmente no son direcciones de memoria, etc. Véase¿Qué NO son las Referencias?para más información. Las referencias son alias de la tabla de símbolos. Observe que en PHP el nombre de la variable y el contenido de la variable son cosas diferentes, por lo que el mismo contenido puede tener diferentes nombres. La analogía más próxima es con los archivos y los nombres de archivos de Unix - los nombres de variables son entradas de directorio, mientras que el contenido de las variables es el archivo en sí. Las referencias se pueden vincular a enlaces duros en sistemas de archivos Unix.



¿Qué hacen las referencias?

Hay tres operaciones básicas que se realizan usando referencias:asignar por referencia,pasar por referencia, ydevolver por referencia. En esta sección se dará una introducción a estas operaciones, con enlaces para una lectura complementaria.

Asignar por Referencia

En la primera de estas operaciones, las referencias de PHP permiten hacer que dos variables hagan referencia al mismo contenido. Es decir, cuando se hace:

<?php
$a
=&$b;
?>
significa que$ay$bapuntan al mismo contenido.

Nota:

$ay$baquí son completamente iguales.$ano está apuntando a$bo viceversa.$ay$bestán apuntando al mismo lugar.

Nota:

Si se asigna, pasa, o devuelve una variable no definida por referencia, la variable se creará.

Ejemplo #1 Usar referencias con variables no definidas

<?php
functionfoo(&$var) { }

foo($a);// $a es "creada" y asignada a null

$b= array();
foo($b['b']);
var_dump(array_key_exists('b',$b));// bool(true)

$c= newStdClass;
foo($c->d);
var_dump(property_exists($c,'d'));// bool(true)
?>

Se puede usar la misma sintaxis con funciones que devuelven referencias:

<?php
$foo
=&find_var($bar);
?>
Desde PHP 5,newdevuelve una referencia automáticamente, por lo que usar=&en este contexto es obsoleto y produce un mensajeE_DEPRECATEDen PHP 5.3 y posteriores, y un mensajeE_STRICTen versiones anteriores. A partir de PHP 7.0 es sintácticamente inválido. (Técnicamente, la diferencia es que, en PHP 5, las variables de objetos, como los recursos, son meros punteros a la información del objeto actual, por lo que estas referencias a objetos no son "referencias" en el mismo sentido usado antes (alias). Para más información, véaseObjetos y referencias.)

Advertencia

Si se asigna una referencia a una varible declaradaglobaldentro de una función, la referencia será visible sólo dentro de la función. Se puede evitar esto usando la matriz$GLOBALS.

Ejemplo #2 Refenciar variables globales dentro de funciones

<?php
$var1
="Variable de ejemplo";
$var2="";

function
referencias_globales($usar_globals)
{
global
$var1,$var2;
if (!
$usar_globals) {
$var2=&$var1;// visible sólo dentro de la función
} else {
$GLOBALS["var2"] =&$var1;// visible también en el contexto global
}
}

referencias_globales(false);
echo
"var2 está establecida a '$var2'\n";// var2 está establecida a ''
referencias_globales(true);
echo
"var2 está establecida a '$var2'\n";// var2 está establecida a 'Variable de ejemplo'
?>
Piense englobal $var;como simplificación de$var =& $GLOBALS['var'];. De este modo, al asignar otra referencia a$varsólo cambia la referencia de la variable local.

Nota:

Si se asigna un valor a una variable con referencias en una sentenciaforeach, también se modifican las referencias.

Ejemplo #3 Referencias y la sentencia foreach

<?php
$ref
=0;
$fila=&$ref;
foreach (array(
1,2,3) as$fila) {
// hacer algo
}
echo
$ref;// 3 - último elemento de la matriz iterada
?>

Mientras que no sea estrictamente una asignación por referencia, las expresiones creadas con el constructor de lenguajearray()también pueden comportarse como tales prefijando&al elemento del array a añadir. Ejemplo:

<?php
$a
=1;
$b= array(2,3);
$arr= array(&$a, &$b[0], &$b[1]);
$arr[0]++;$arr[1]++;$arr[2]++;
/* $a == 2, $b == array(3, 4); */
?>

Observe, sin embargo, que las referencias dentro de arrays son potencialmente peligrosas. Realizar una asignación normal (no por referencia) con una referencia en el lado derecho no convierte el lado izquierdo en una referencia, pero las referencias dentro de arrays son conservadas en estas asignaciones normales. Esto también se aplica a las llamadas a funciones donde el array es pasado por valor. Ejemplo:

<?php
/* Asignación de variables escalares */
$a=1;
$b=&$a;
$c=$b;
$c=7;//$c no es una referencia; no cambia $a o $b

/* Asignación de variables de array */
$arr= array(1);
$a=&$arr[0];// $a y $arr[0] son el mismo conjunto de referencias
$arr2=$arr;// ¡no es una asignación por referencia!
$arr2[0]++;
/* $a == 2, $arr == array(2) */
/* ¡El contenido de $arr se cambia incluso si no es una referencia! */
?>
En otras palabras, el comportamiento de las referencias de arrays está definido en una base elemento-por-elemento; el comportamiento de las referencias de elementos individuales está desasociado del estado de la referencia del array contenedor.

Pasar por Referencia

Lo segundo que hacen las referencias es pasar variables por referencia. Esto se lleva a cabo haciendo que una variable local en una función y una variable en el ámbito de la llamada referencien al mismo contenido. Ejemplo:

<?php
functionfoo(&$var)
{
$var++;
}

$a=5;
foo($a);
?>
hará que$asea 6. Esto sucede porque en la funciónfoola variable$varhace referencia al mismo contenido que$a. Para más información sobre esto, lea la secciónpasar por referencia.

Devolver por Referencia

Lo tercero que hacen las referncias esdevolver por referencia.



¿Qué NO son las Referencias?

Como se dijo antes, las referencias no son punteros. Es decir, la siguiente construcción no hará lo que se esperaba:

<?php
functionfoo(&$var)
{
$var=&$GLOBALS["baz"];
}
foo($bar);
?>

Lo que sucede es que$varenfooserá ligada con$baren la llamada, pero entonces será religada con$GLOBALS["baz"]. No hay forma de ligar$baren el ámbito de la llamada a otra cosa usando el mecanismo de referencia, ya que$barno está disponible en la funciónfoo(está representada por$var, pero$varsólo tiene el contenido de la variable y no la vinculación nombre-a-valor en la tabla de símbolos de llamada). Se puede usardevolver referenciaspara referencias variables seleccionadas por la función.



Pasar por Referencia

Se puede pasar una variable por referencia a una función y así hacer que la función pueda modificar la variable. La sintaxis es la siguiente:

<?php
functionfoo(&$var)
{
$var++;
}

$a=5;
foo($a);
// $a es 6 aquí
?>

Nota:No existe ningún signo de referencia en una llamada a una función - sólo en la definición de la función. Las definiciones de funciones por sí solas son suficientes para pasar correctamente el argumento por referencia. A partir de PHP 5.3.0, se obtendrá una advertencia diciendo que "call-time pass-by-reference" (pasar por referencia en tiempo de llamada) está obsoleto cuando se use & enfoo(&$a);. A partir de PHP 5.4.0, el paso por referencia en tiempo de llamada ha sido eliminado, por lo que su uso emitirá un error fatal.

Se puede pasar por referencia lo siguiente:

  • Variables, esto es,foo($a)
  • Referencias devueltas desde funciones, esto es:

    <?php
    functionfoo(&$var)
    {
    $var++;
    }
    function &
    bar()
    {
    $a=5;
    return
    $a;
    }
    foo(bar());
    ?>
    Vea más sobredevolver por referencia.

Ninguna otra expresión debería pasarse por referencia, ya que el resultado no está definido. Por ejemplo, los siguientes ejemplos de pasar por referencia no son válidos:

<?php
functionfoo(&$var)
{
$var++;
}
function
bar()// Observe que falta el &
{
$a=5;
return
$a;
}
foo(bar());// Produce un error fatal a partir de PHP 5.0.5,un aviso de estándar estricto
// a partir de PHP 5.1.1, y un aviso a partir de PHP 7.0.0

foo($a=5);// Expresión, no una variable
foo(5);// Produce un error fatal

classFoobar
{
}

foo(newFoobar())// Produce un aviso a partir de PHP 7.0.7
// Observación: Solo las variables deben pasarse por referencia
?>



Devolver Referencias

Devolver por referencia es útil cuando se quiere usar una función para encontrar a qué variable debería estar vinculada una referencia.Nouse devolver por referencia para aumentar el rendimiento. El motor optimizará automáticamente esto por sí mismo. Hay que devolver referencias sólo cuando se tenga una razón técnicamente válida para hacerlo. Para devolver referencias use esta sintaxis:

<?php
classfoo{
public
$valor=42;

public function &
obtenerValor() {
return
$this->valor;
}
}

$obj= newfoo;
$miValor= &$obj->obtenerValor();// $miValor es una referencia a $obj->valor, que es 42.
$obj->valor=2;
echo
$miValor;// imprime el nuevo valor de $obj->valor, esto es, 2.
?>
En este ejemplo, la propiedad del objeto devuelto por la funciónobtenerValordebería estar establecida, no la copia, como si estuviera sin usar la sintaxis de referencia.

Nota:A diferencia de pasar un parámetro, aquí se tiene que usar&en ambos lugares - para indicar que se quiere devolver por referencia, no una copia, y para indicar que la vinculación por referencia, en vez de la asignación normal, debería ser hecha para$miValor.

Nota:Si se intenta devolver una referencia desde una función con la sintaxis:return ($this->valor);,nofuncionará ya que se está intentando devolver el resultado de unaexpresión, y no de una variable, por referencia. Sólo se puede devolver variables por referencia desde una función - nada más. Desde PHP 5.1.0, se emite un errorE_NOTICEsi el código intenta devolver una expresión dinámica o un resultado del operadornew.

Para usar la referencia retornada, se debe usar la asignación por referencia:

<?php
function &collector() {
static
$collection= array();
return
$collection;
}
$collection= &collector();
$collection[] ='foo';
?>
Para pasar la referencia retornada a otra función que espera una referencia se puede usar la siguiente sintaxis:
<?php
function &collector() {
static
$collection= array();
return
$collection;
}
array_push(collector(),'foo');
?>

Nota:Observe quearray_push(&collector(), 'foo');nofuncionará, resultará en un error fatal.



Destruir Referencias

Cuando se destruye una referencia, se rompe el vínculo entre el nombre de la variable y el contenido de la variable. Esto no significa que el contenido de la variable sea destruida. Por ejemplo:

<?php
$a
=1;
$b=&$a;
unset(
$a);
?>
no destruirá$b, sólo$a.

De nuevo, podría ser útil pensar en esto como análogo a una llamada aunlinkde Unix.



Ubicar las Referencias

Muchas construcciones sintácticas de PHP están implementadas mediante el mecanismo de referencia, por lo que todo lo mencionado aquí sobre la vinculación de referencias también se aplica a estas construcciones. Algunas construcciones, como pasar y devolver por referencia, han sido mencionadas antes. Otras construcciones que usan referencias son:

Referencias globales

Cuando se declara una variable comoglobal $var, de hecho se está creando una referencia a una variable global. Es decir, esto es lo mismo que:

<?php
$var
=&$GLOBALS["var"];
?>

Esto también significa que al destruir$varno se destruirá la variable global.

$this

En un método de un objeto,$thises siempre una referencia al objeto llamado.




Variables predefinidas

PHP proporciona una gran cantidad de variables predefinidas para todos los scripts. Las variables representan de todo, desdevariables externashasta variables de entorno incorporadas, desde los últimos mensajes de error hasta los últimos encabezados recuperados.


Superglobals

SuperglobalsSuperglobals son variables internas que están disponibles siempre en todos los ámbitos

Descripción

Algunas variables predefinidas en PHP son "superglobales", lo que significa que están disponibles en todos los ámbitos a lo largo del script. No es necesario emplearglobal $variable;para acceder a ellas dentro de las funciones o métodos.

Las variables superglobals son:

Notas

Nota:Disponibilidad de variables

Por defecto, todas las superglobals están disponibles pero hay directivas que afectan a su disponibilidad. Para más información, véase la documentacion devariables_order.

Nota:Variables variables

Las variables superglobals no pueden ser usadas comovariables variablesdentro de funciones o métodos de clase.



$GLOBALS

(PHP 4, PHP 5, PHP 7, PHP 8)

$GLOBALSHace referencia a todas las variables disponibles en el ámbito global

Descripción

Es unarrayasociativo que contiene las referencias a todas la variables que están definidas en el ámbito global del script. Los nombres de las variables son las claves del array.

Ejemplos

Ejemplo #1 Ejemplo de$GLOBALS

<?php
functiontest() {
$foo="variable local";

echo
'$foo en el ámbito global: '.$GLOBALS["foo"] ."\n";
echo
'$foo en el ámbito simple: '.$foo."\n";
}

$foo="Contenido de ejemplo";
test();
?>

El resultado del ejemplo sería algo similar a:

$foo en el ámbito global: Contenido de ejemplo
$foo en el ámbito simple: variable local

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.

Nota:Disponibilidad de las variables

A diferencia de todas las otrassuperglobals,$GLOBALSha estado esencialmente siempre disponible en PHP.



$_SERVER

$HTTP_SERVER_VARS [eliminado]

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SERVER--$HTTP_SERVER_VARS [eliminado]Información del entorno del servidor y de ejecución

Descripción

$_SERVERes un array que contiene información, tales como cabeceras, rutas y ubicaciones de script. Las entradas de este array son creadas por el servidor web. No hay garantía que cada servidor web proporcione alguna de estas entradas, existen servidores que pueden omitir algunas o proporcionar otras no recogidas aquí. Un gran número de estas variables se encuentran recogidas en» especificación CGI 1.1, así que al menos debe esperar encontrar estas entradas.

Nota:Antes de PHP 5.4.0,$HTTP_SERVER_VARScontenía la misma información inicial, aunque no era unasuperglobal. (Observe que$HTTP_SERVER_VARSy$_SERVEReran variables diferentes, por lo que PHP las trata de forma distinta).

Índices

Puede encontrar o no los siguientes elementos en$_SERVER. Tenga en cuenta que si ejecuta PHP desdelínea de comandopocos o ninguno de los siguientes elementos estarán disponibles (o tendrán algún significado).

'PHP_SELF'
El nombre del archivo de script ejecutándose actualmente, relativa al directorio raíz de documentos del servidor. Por ejemplo, el valor de$_SERVER['PHP_SELF']en un script ejecutado en la direcciónhttp://example.com/foo/bar.phpserá/foo/bar.php. La constante__FILE__contiene la ruta completa del fichero actual, incluyendo el nombre del archivo.Si PHP se está ejecutando como un proceso de línea de comando, esta variable es el nombre del script desde PHP 4.3.0. En anteriores versiones no estaba disponible.
'argv'
Array de los argumentos enviados al script. Cuando se ejecuta el script en línea de comando se obtiene acceso a los parámetros de línea de comando con un estilo parecido a como sería en C. Cuando se ejecuta el script mediante el método GET, contendrá la cadena de la consulta.
'argc'
Contiene el número de parámetros de línea de comando enviados al script (si se ejecuta en línea de comando).
'GATEWAY_INTERFACE'
Número de revisión de la especificación CGI que está empleando el servidor, por ejemplo 'CGI/1.1'.
'SERVER_ADDR'
La dirección IP del servidor donde se está ejecutando actualmente el script.
'SERVER_NAME'
El nombre del host del servidor donde se está ejecutando actualmente el script. Si el script se ejecuta en un host virtual se obtendrá el valor del nombre definido para dicho host virtual.

Nota:Bajo Apache 2, se debe establecerUseCanonicalName = OnyServerName. De lo contrario, este valor refleja el nombre del host proporcionado por el cliente, el cual se puede burlar. No es seguro depender de este valor en contextos que necesiten seguridad.

'SERVER_SOFTWARE'
Cadena de identificación del servidor dada en las cabeceras de respuesta a las peticiones.
'SERVER_PROTOCOL'
Nombre y número de revisión del protocolo de información a través del cual la página es solicitada, por ejemplo 'HTTP/1.0'.
'REQUEST_METHOD'
Método de petición empleado para acceder a la página, por ejemplo 'GET', 'HEAD', 'POST', 'PUT'.

Nota:

El script de PHP se considera terminado después de enviar las cabeceras (es decir después de producir cualquier resultado sin emplear buffers para el resultado) si el método de la petición empleado eraHEAD.

'REQUEST_TIME'
Fecha Unix de inicio de la petición. Disponible desde PHP 5.1.0.
'REQUEST_TIME_FLOAT'
El timestamp del inicio de la solicitud, con precisión microsegundo. Disponible desde PHP 5.4.0.
'QUERY_STRING'
Si existe, la cadena de la consulta de la petición de la página.
'DOCUMENT_ROOT'
El directorio raíz de documentos del servidor en el cual se está ejecutando el script actual, según está definida en el archivo de configuración del servidor.
'HTTP_ACCEPT'
Contenido de la cabeceraAccept:de la petición actual, si existe.
'HTTP_ACCEPT_CHARSET'
Contenido de la cabeceraAccept-Charset:de la petición actual, si existe. Por ejemplo: 'iso-8859-1,*,utf-8'.
'HTTP_ACCEPT_ENCODING'
Contenido de la cabeceraAccept-Encoding:de la petición actual, si existe. Por ejemplo: 'gzip'.
'HTTP_ACCEPT_LANGUAGE'
Contenido de la cabeceraAccept-Language:de la petición actual, si existe. Por ejemplo: 'en'.
'HTTP_CONNECTION'
Contenido de la cabeceraConnection:de la petición actual, si existe. Por ejemplo: 'Keep-Alive'.
'HTTP_HOST'
Contenido de la cabeceraHost:de la petición actual, si existe.
'HTTP_REFERER'
Dirección de la pagina (si la hay) que emplea el agente de usuario para la pagina actual. Es definido por el agente de usuario. No todos los agentes de usuarios lo definen y algunos permiten modificarHTTP_REFERERcomo parte de su funcionalidad. En resumen, es un valor del que no se puede confiar realmente.
'HTTP_USER_AGENT'
Contenido de la cabeceraUser-Agent:de la petición actual, si existe. Consiste en una cadena que indica el agente de usuario empleado para acceder a la pagina. Un ejemplo típico es:Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586). Entre otras opciones, puede emplear dicho valor conget_browser()para personalizar el resultado de la salida de la página en función de las capacidades del agente de usuario empleado.
'HTTPS'
Ofrece un valor no vacío si el script es pedido mediante el protocolo HTTPS.

Nota:Tenga en cuenta que si se emplea ISAPI con IIS el valor seráoffsi la petición no se ha realizado a través del protocolo HTTPS.

'REMOTE_ADDR'
La dirección IP desde la cual está viendo la página actual el usuario.
'REMOTE_HOST'
El nombre del host desde el cual está viendo la página actual el usuario. La obtención inversa del dns está basada en laREMOTE_ADDRdel usuario.

Nota:Su servidor web debe estar configurado para crear esta variable. Por ejemplo en Apache necesita que existaHostnameLookups Ondentro dehttpd.conf. Consulte tambiengethostbyaddr().

'REMOTE_PORT'
El puerto empleado por la máquina del usuario para comunicarse con el servidor web.
'REMOTE_USER'
El usuario autenticado.
'REDIRECT_REMOTE_USER'
El usuario autenticado si la petición es redirigida internamente.
'SCRIPT_FILENAME'

La ruta del script ejecutándose actualmente en forma absoluta.

Nota:

Si un script se ejecuta mediante CLI como ruta relativa, como por ejemplofile.phpo../file.php, entonces$_SERVER['SCRIPT_FILENAME']contendrá la ruta relativa especificada por el usuario.

'SERVER_ADMIN'
El valor dado a la directiva SERVER_ADMIN (de Apache) en el archivo de configuración del servidor web. Si el script se está ejecutando en un host virtual, el valor dado será el definido para dicho host virtual.
'SERVER_PORT'
El puerto de la máquina del servidor usado por el servidor web para la comunicación. Para las configuraciones por omisión, el valor será '80'; el empleo de SSL, por ejemplo, cambiará dicho valor al valor definido para el puerto HTTP seguro.

Nota:Bajo Apache 2, se debe establecerUseCanonicalName = On, así comoUseCanonicalPhysicalPort = Onpara poder obtener el puerto físico (real), de otro modo, este valor podría ser burlado y podría o no devolver el valor del puerto físico. No es seguro confiar en este valor en contextos que requieran seguridad.

'SERVER_SIGNATURE'
Cadena que contiene la versión del servidor y el nombre del host virtual que son añadidas a las páginas generadas por el servidor, si esta habilitada esta funcionalidad.
'PATH_TRANSLATED'
Ruta de acceso basada en el sistema (no en el directorio raíz de documentos del servidor) del script actual, después de cualquier mapeo de virtual a real realizada por el servidor.

Nota:A partir de PHP 4.3.2,PATH_TRANSLATEDno está definida de forma implícita en elSAPIde Apache 2, en comparación a la situación de Apache 1, donde era necesario establecer el mismo valor que la variable del servidorSCRIPT_FILENAMEcuando no era proporcionada por Apache. Este cambio ha sido realizado para cumplir la especificaciónCGIdondePATH_TRANSLATEDsólo debe existir siPATH_INFOesta definida.Los usuarios de Apache 2 pueden emplearAcceptPathInfo = Ondentro dehttpd.confpara definirPATH_INFO.

'SCRIPT_NAME'
Contiene la ruta del script actual. Esto es de utilidad para las páginas que necesiten apuntarse a si mismas. La constante__FILE__contiene la ruta absoluta y el nombre del archivo actual incluido.
'REQUEST_URI'
La URI que se empleó para acceder a la página. Por ejemplo: '/index.html'.
'PHP_AUTH_DIGEST'
Cuando se hace autenticación Digest HTTP, esta variable se establece para el encabezado 'Authorization' enviado por el cliente (el cual se debe entonces usar para hacer la validación apropiada).
'PHP_AUTH_USER'
Cuando se hace autenticación HTTP, esta variable se establece para el nombre de usuario provisto por el usuario.
'PHP_AUTH_PW'
Cuando se hace autenticación HTTP, esta variable se establece para la clave provista por el usuario.
'AUTH_TYPE'
Cuando se realiza la autenticación HTTP, está variable se establece para el tipo de autenticación.
'PATH_INFO'
Contiene cualquier información sobre la ruta proporcionada por el cliente a continuación del nombre del fichero del script actual pero antecediendo a la cadena de la petición, si existe. Por ejemplo, si el script actual se accede a través de la URLhttp://www.example.com/php/path_info.php/some/stuff?foo=bar, entonces$_SERVER['PATH_INFO']contendrá/some/stuff.
'ORIG_PATH_INFO'
Versión original de 'PATH_INFO' antes de ser procesado por PHP.

Historial de cambios

VersiónDescripción
5.4.0$HTTP_SERVER_VARSya no está disponible debido a la eliminación de arrays grandes de registro.
5.3.0La directivaregister_long_arrays, la cual hacía que estuviera disponible$HTTP_SERVER_VARSestá obsoleta.

Ejemplos

Ejemplo #1Ejemplo de $_SERVER

<?php
echo$_SERVER['SERVER_NAME'];
?>

El resultado del ejemplo sería algo similar a:

www.example.com

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.

Ver también



$_GET

$HTTP_GET_VARS [obsoleta]

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET--$HTTP_GET_VARS [obsoleta]Variables HTTP GET

Descripción

Un array asociativo de variables pasado al script actual vía parámetros URL (también conocida como cadena de consulta). Tenga en cuenta que el array no solo se rellena para las solicitudes GET, sino para todas las solicitudes con una cadena de consulta.

$HTTP_GET_VARScontiene la misma información, pero no es unasuperglobal. (Note que$HTTP_GET_VARSy$_GETson diferentes variables y que PHP los usa de forma diferente)

Ejemplos

Ejemplo #1 Ejemplo de$_GET

<?php
echo'¡Hola '.htmlspecialchars($_GET["nombre"]) .'!';
?>

Asumiendo que el usuario introdujo http://example.com/?nombre=Hannes

El resultado del ejemplo sería algo similar a:

¡Hola Hannes!

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.

Nota:

Las variables GET son pasadas víaurldecode().



$_POST

$HTTP_POST_VARS [obsoleta]

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_POST--$HTTP_POST_VARS [obsoleta]Variables POST de HTTP

Descripción

Un array asociativo de variables pasadas al script actual a través del método POST de HTTP cuando se empleaapplication/x-www-form-urlencodedomultipart/form-datacomo Content-Type de HTTP en la petición.

$HTTP_POST_VARScontiene la misma información inicial, aunque no es unasuperglobal. (Observe que$HTTP_POST_VARSy$_POSTson variables diferentes, por lo que PHP las trata de forma distinta).

Ejemplos

Ejemplo #1 Ejemplo de$_POST

<?php
echo'¡Hola '.htmlspecialchars($_POST["nombre"]) .'!';
?>

Asumiendo que el usuario envió por el método POST nombre=Juan

El resultado del ejemplo sería algo similar a:

¡Hola Juan!

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.



$_FILES

$HTTP_POST_FILES [obsoleta]

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES--$HTTP_POST_FILES [obsoleta]Variables de subida de ficheros HTTP

Descripción

Unarrayasociativo de elementos subidos al script en curso a través del método POST. La estructura de este array se resume en la secciónSubidas con el método POST.

$HTTP_POST_FILEScontiene la misma información inicial, pero no essuperglobal. (Observe que$HTTP_POST_FILESy$_FILESson variables diferentes y que PHP las trata como tal).

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.

Ver también



$_REQUEST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_REQUESTVariables HTTP Request

Descripción

Unarrayasociativo que por defecto contiene el contenido de$_GET,$_POSTy$_COOKIE.

Historial de cambios

VersiónDescripción
5.3.0Se introdujorequest_order. Esta directiva afecta al contenido de$_REQUEST.

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.

Nota:

Cuando se ejecuta en lalínea de comandos,nose incluirán las entradasargvyargc; ya que están presentes en elarray$_SERVER

Nota:

Las variables en$_REQUESTse proporcionan al script a través de los mecanismos de entrada GET, POST, y COOKIE y por lo tanto pueden ser manipulados por el usuario remoto y no debe confiar en el contenido. La presencia y el orden de las variables listadas en este array se definen según la directiva de configuración PHPvariables_order.

Ver también



$_SESSION

$HTTP_SESSION_VARS [obsoleta]

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION--$HTTP_SESSION_VARS [obsoleta]Variables de sesión

Descripción

Es un array asociativo que contiene variables de sesión disponibles para el script actual. Ver la documentación deFunciones de sesiónpara más información sobre su uso.

$HTTP_SESSION_VARScontiene la misma información inicial pero no es unasuperglobal. (Nótese que$HTTP_SESSION_VARSy$_SESSIONson diferentes variables y PHP las trata de forma distinta)

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.

Ver también



$_ENV

$HTTP_ENV_VARS [obsoleta]

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_ENV--$HTTP_ENV_VARS [obsoleta]Variables de entorno

Descripción

Una variable tipoarrayasociativo de variables pasadas al script actual a través del método del entorno.

Estas variables son importadas en el espacio de nombres global de PHP desde el entorno bajo el que está siendo ejecutado el intérprete PHP. Muchas son entregadas por el intérprete de comandos bajo el que PHP está corriendo y diferentes sistemas suelen tener diferentes tipos de intérpretes de comandos, una lista definitiva es imposible. Por favor consulte la documentación de su intérprete de comandos para una lista de las variables de entorno que se definen.

Otras variables de entorno incluyen las variables CGI, colocadas allí independientemente de que PHP esté siendo ejecutado como módulo del servidor o procesador CGI.

$HTTP_ENV_VARScontiene la misma información inicial, pero no es unasuperglobal. (Note que$HTTP_ENV_VARSy$_ENVson variables diferentes y que PHP las trata como tal)

Ejemplos

Ejemplo #1 Ejemplo de$_ENV

<?php
echo'¡Mi nombre de usuario es '.$_ENV["USER"] .'!';
?>

Asumiendo que "bjori" ejecuta este script

El resultado del ejemplo sería algo similar a:

¡Mi nombre de usuario es bjori!

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.

Ver también



$_COOKIE

$HTTP_COOKIE_VARS [obsoleta]

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_COOKIE--$HTTP_COOKIE_VARS [obsoleta]Cookies HTTP

Descripción

Una variable tipoarrayasociativo de variables pasadas al script actual a través de Cookies HTTP.

$HTTP_COOKIE_VARScontiene la misma información inicial, pero no es unasuperglobal. (Note que$HTTP_COOKIE_VARSy$_COOKIEson variables diferentes y que PHP las trata como tal)

Ejemplos

Ejemplo #1 Ejemplo de$_COOKIE

<?php
echo'¡Hola '.htmlspecialchars($_COOKIE["nombre"]) .'!';
?>

Asumiendo que la cookie "nombre" ha sido definida anteriormente

El resultado del ejemplo sería algo similar a:

¡Hola Juan!

Notas

Nota:

Esta es una 'superglobal' o una variable automatic global. Significa simplemente que es una variable que está disponible en cualquier parte del script. No hace falta hacerglobal $variable;para acceder a la misma desde funciones o métodos.



$php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsgEl mensaje de error anterior

Advertencia

Esta característica ha sido declaradaOBSOLETAa partir de PHP 7.2.0. Su uso está totalmente desaconsejado.

Utiliceerror_get_last()en su lugar.

Descripción

$php_errormsges una variable que contiene el texto del último mensaje de error generado por PHP. Esta variable solo estará disponible dentro del ámbito donde ocurrió el error, y solamente funcionará si la opción de configuracióntrack_errorsestá activada (por defecto está desactivada).

Advertencia

Si está definido un manejador de errores (set_error_handler()),$php_errormsgestará establecido solamente si el manejador de errores devuelvefalse

Ejemplos

Ejemplo #1 Ejemplo de$php_errormsg

<?php
@strpos();
echo
$php_errormsg;
?>

El resultado del ejemplo sería algo similar a:

Wrong parameter count for strpos()

Ver también



$http_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$http_response_headerEncabezados de respuesta HTTP

Descripción

Elarray$http_response_headeres similar a la functiónget_headers(). Cuando se hace uso deHTTP wrapper,$http_response_headerserá poblado con los encabezados de respuesta HTTP.$http_response_headerserá creada en elámbito local.

Ejemplos

Ejemplo #1 Ejemplo de$http_response_header

<?php
functionget_contents() {
file_get_contents("http://example.com");
var_dump($http_response_header);
}
get_contents();
var_dump($http_response_header);
?>

El resultado del ejemplo sería algo similar a:

array(9) {
  [0]=>
  string(15) "HTTP/1.1 200 OK"
  [1]=>
  string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
  [2]=>
  string(29) "Server: Apache/2.2.3 (CentOS)"
  [3]=>
  string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
  [4]=>
  string(27) "ETag: "280100-1b6-80bfd280""
  [5]=>
  string(20) "Accept-Ranges: bytes"
  [6]=>
  string(19) "Content-Length: 438"
  [7]=>
  string(17) "Connection: close"
  [8]=>
  string(38) "Content-Type: text/html; charset=UTF-8"
}
NULL



$argc

(PHP 4, PHP 5, PHP 7, PHP 8)

$argcEl número de argumentos pasados a un script

Descripción

Contiene el número de argumentos pasados al script actual cuando se ejecuta desde lalínea de comandos.

Nota:El nombre del script es pasado siempre como argumento del script, por lo tanto, el valor mínimo de$argces1.

Nota:Esta variable sólo está disponible cuandoregister_argc_argvestá activado.

Ejemplos

Ejemplo #1 Ejemplo de$argc

<?php
var_dump
($argc);
?>

Cuando se ejecuta el ejemplo con: php script.php arg1 arg2 arg3

El resultado del ejemplo sería algo similar a:

int(4)

Notas

Nota:

Esto también está disponible como$_SERVER['argc'].

Ver también

  • getopt()- Obtiene las opciones de la lista de argumentos de la línea de comandos
  • $argv



$argv

(PHP 4, PHP 5, PHP 7, PHP 8)

$argvArray de argumentos pasados a un script

Descripción

Contiene unarrayde todos los argumentos pasados a un script cuando se ejecuta desde lalínea de comandos.

Nota:El primer argumento$argv[0]siempre es el nombre del fichero que fue usado para ejecutar el script.

Nota:Esta variable no está disponible siregister_argc_argvestá deshabilitado.

Ejemplos

Ejemplo #1 Ejemplo de$argv

<?php
var_dump
($argv);
?>

Cuando se ejecuta el ejemplo con: php script.php arg1 arg2 arg3

El resultado del ejemplo sería algo similar a:

array(4) {
  [0]=>
  string(10) "script.php"
  [1]=>
  string(4) "arg1"
  [2]=>
  string(4) "arg2"
  [3]=>
  string(4) "arg3"
}

Notas

Nota:

Esto también está disponible como$_SERVER['argv'].

Ver también

  • getopt()- Obtiene las opciones de la lista de argumentos de la línea de comandos
  • $argc


Tabla de contenidos

  • Superglobals— Superglobals son variables internas que están disponibles siempre en todos los ámbitos
  • $GLOBALS— Hace referencia a todas las variables disponibles en el ámbito global
  • $_SERVER— Información del entorno del servidor y de ejecución
  • $_GET— Variables HTTP GET
  • $_POST— Variables POST de HTTP
  • $_FILES— Variables de subida de ficheros HTTP
  • $_REQUEST— Variables HTTP Request
  • $_SESSION— Variables de sesión
  • $_ENV— Variables de entorno
  • $_COOKIE— Cookies HTTP
  • $php_errormsg— El mensaje de error anterior
  • $http_response_header— Encabezados de respuesta HTTP
  • $argc— El número de argumentos pasados a un script
  • $argv— Array de argumentos pasados a un script


Excepciones predefinidas

Tabla de contenidos

Véanse también lasExcepciones de la SPL


Exception

(PHP 5, PHP 7, PHP 8)

Introducción

Exceptiones la clase base para todas las excepciones en PHP 5, y la clase base para todas las excepciones de usuario en PHP 7.

Antes de PHP 7,Exceptionno implementa la interfazThrowable.

Sinopsis de la Clase

classExceptionimplementsThrowable{
/* Propiedades */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos */
public__construct(string$message= "",int$code= 0,Throwable$previous=null)
finalpublicgetMessage():string
finalpublicgetPrevious():Throwable
finalpublicgetCode():mixed
finalpublicgetFile():string
finalpublicgetLine():int
finalpublicgetTrace():array
finalpublicgetTraceAsString():string
public__toString():string
finalprivate__clone():void
}

Propiedades

message

El mensaje de la excepción

code

El código de la excepción

file

El nombre del fichero donde se originó la excepción

line

La línea donde se originó la excepción


Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__constructConstructor de la excepción

Descripción

publicException::__construct(string$message= "",int$code= 0,Throwable$previous=null)

Construye el objeto Exception.

Parámetros

message

Mensaje de la excepción a lanzar.

code

El código de la excepción.

previous

La excepción previa utilizada por la serie de excepciones.

Nota:Llamar al constructor de la clase Exception de una subclase ignora los argumentos por omisión, si las propiedades $code y $message ya están establecidas.

Historial de cambios

VersiónDescripción
7.0.0El parámetropreviousahora es del tipoThrowable.
5.3.0Se añadió el parámetroprevious.

Notas

Nota:

messageNOes seguro binariamente.



Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessageObtiene el mensaje de Excepción

Descripción

finalpublicException::getMessage():string

Devuelve el mensaje de Excepción.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el mensaje de Excepción en formato cadena.

Ejemplos

Ejemplo #1 Ejemplo deException::getMessage()

<?php
try {
throw new
Exception("Algún mensaje de error");
} catch(
Exception $e) {
echo
$e->getMessage();
}
?>

El resultado del ejemplo sería algo similar a:

Algún mensaje de error

Ver también



Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPreviousDevuelve la excepción anterior

Descripción

finalpublicException::getPrevious():Throwable

Devuelve la excepción anterior (el tercer parámetro deException::__construct()).

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve laThrowableanterior si está disponible onullsi no.

Historial de cambios

VersiónDescripción
7.0.0La declaración de tipo de retorno cambió aThrowable.

Ejemplos

Ejemplo #1 Ejemplo deException::getPrevious()

Recorrer, e imprimir la traza de una excepción.

<?php
classMiPropiaExcepciónextendsException{}

function
hacerCosas() {
try {
throw new
InvalidArgumentException("¡Lo está haciendo mal!",112);
} catch(
Exception $e) {
throw new
MiPropiaExcepción("Ocurrió algo",911,$e);
}
}


try {
hacerCosas();
} catch(
Exception $e) {
do {
printf("%s:%d %s (%d) [%s]\n",$e->getFile(),$e->getLine(),$e->getMessage(),$e->getCode(),get_class($e));
} while(
$e=$e->getPrevious());
}
?>

El resultado del ejemplo sería algo similar a:

/home/bjori/ex.php:8 Ocurrió algo (911) [MiPropiaExcepción]
/home/bjori/ex.php:6 ¡Lo está haciendo mal! (112) [InvalidArgumentException]

Ver también



Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCodeObtiene el código de una excepción

Descripción

finalpublicException::getCode():mixed

Devuelve el código de una excepción.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el código de Excepción en forma deintegerenExceptionpero posiblemente en forma de otros tipos enExceptiondescendientes (por ejemplo comostringenPDOException).

Ejemplos

Ejemplo #1 Ejemplo deException::getCode()

<?php
try {
throw new
Exception("Un mensaje de error",30);
} catch(
Exception $e) {
echo
"El código de excepción es: ".$e->getCode();
}
?>

El resultado del ejemplo sería algo similar a:

El código de excepción es: 30

Ver también



Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFileObtiene el fichero en el que se creó la excepción

Descripción

finalpublicException::getFile():string

Obtiene el nombre del fichero en el que fue creada la excepción.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre del fichero en donde fue creada la excepción.

Ejemplos

Ejemplo #1 Ejemplo deException::getFile()

<?php
try {
throw new
Exception;
} catch(
Exception $e) {
echo
$e->getFile();
}
?>

El resultado del ejemplo sería algo similar a:

/home/bjori/tmp/ex.php

Ver también



Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLineObtiene la línea en el que se creó la excepción

Descripción

finalpublicException::getLine():int

Devuelve el número de la línea donde se creó la excepción.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el número de la línea donde se creó la excepción.

Ejemplos

Ejemplo #1 Ejemplo deException::getLine()

<?php
try {
throw new
Exception("Algún mensaje de error");
} catch(
Exception $e) {
echo
"La excepción se creó en la línea: ".$e->getLine();
}
?>

El resultado del ejemplo sería algo similar a:

La excepción se creó en la línea: 3

Ver también



Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTraceObtiene la traza de la pila

Descripción

finalpublicException::getTrace():array

Devuelve la traza de pila de una excepción.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el seguimiento de pila de una excepción como unarray.

Ejemplos

Ejemplo #1 Ejemplo deException::getTrace()

<?php
functiontest() {
throw new
Exception;
}

try {
test();
} catch(
Exception $e) {
var_dump($e->getTrace());
}
?>

El resultado del ejemplo sería algo similar a:

array(1) {
  [0]=>
  array(4) {
    ["file"]=>
    string(22) "/home/bjori/tmp/ex.php"
    ["line"]=>
    int(7)
    ["function"]=>
    string(4) "test"
    ["args"]=>
    array(0) {
    }
  }
}

Ver también



Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsStringObtiene la traza de la pila como una cadena de caracteres

Descripción

finalpublicException::getTraceAsString():string

Devuelve la traza de la pila de una excepción como una cadena de caracteres.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returns the Exception stack trace as a string.

Ejemplos

Ejemplo #1 Ejemplo deException::getTraceAsString()

<?php
functiontest() {
throw new
Exception;
}

try {
test();
} catch(
Exception $e) {
echo
$e->getTraceAsString();
}
?>

El resultado del ejemplo sería algo similar a:

#0 /home/bjori/tmp/ex.php(7): test()
#1 {main}

Ver también



Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toStringRepresentación de la excepción en formato cadena

Descripción

publicException::__toString():string

Devuelve la representación de la excepción en formatostring.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la representación de la excepción en formatostring.

Ejemplos

Ejemplo #1 Ejemplo deException::__toString()

<?php
try {
throw new
Exception("Some error message");
} catch(
Exception $e) {
echo
$e;
}
?>

El resultado del ejemplo sería algo similar a:

exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}

Ver también



Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__cloneClona la excepción

Descripción

finalprivateException::__clone():void

Intenta clonar la Excepción, lo que resultará en un error Fatal.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Las Excepcionesnose pueden clonar.


Tabla de contenidos



ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Introducción

Una excepción de error.

Sinopsis de la Clase

classErrorExceptionextendsException{
/* Propiedades */
protectedint$severity;
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos */
public__construct(
    string$message= "",
    int$code= 0,
    int$severity= E_ERROR,
    string$filename= __FILE__,
    int$lineno= __LINE__,
    Exception$previous=null
)
finalpublicgetSeverity():int
/* Métodos heredados */
finalpublicException::getMessage():string
finalpublicException::getFile():string
finalpublicException::getLine():int
finalpublicException::getTrace():array
finalpublicException::getTraceAsString():string
publicException::__toString():string
finalprivateException::__clone():void
}

Propiedades

severity

La gravedad de la excepción

Ejemplos

Ejemplo #1 Utilizarset_error_handler()para convertir mensajes de error en objetos ErrorException.

<?php
functionexception_error_handler($severidad,$mensaje,$fichero,$línea) {
if (!(
error_reporting() &$severidad)) {
// Este código de error no está incluido en error_reporting
return;
}
throw new
ErrorException($mensaje,0,$severidad,$fichero,$línea);
}
set_error_handler("exception_error_handler");

/* Desencadenar la excepción */
strpos();
?>

El resultado del ejemplo sería algo similar a:

Fatal error: Uncaught exception 'ErrorException' with message 'strpos() expects at least 2 parameters, 0 given' in /home/bjori/tmp/ex.php:12
Stack trace:
#0 [internal function]: exception_error_handler(2, 'strpos() expect...', '/home/bjori/php...', 12, Array)
#1 /home/bjori/php/cleandocs/test.php(12): strpos()
#2 {main}
  thrown in /home/bjori/tmp/ex.php on line 12


ErrorException::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__constructConstructor de la excepción

Descripción

publicErrorException::__construct(
    string$message= "",
    int$code= 0,
    int$severity= E_ERROR,
    string$filename= __FILE__,
    int$lineno= __LINE__,
    Exception$previous=null
)

Construye el objeto Exception.

Parámetros

message

Mensaje de la excepción a lanzar.

code

El código de la excepción.

severity

Nivel de la severidad de la excepción.

Nota:

Aunque la severidad puede ser cuaquier valor de tipointeger, se pretende que se empleen lasconstantes de error.

filename

Nombre del fichero donde se lanzó la excepción.

lineno

Número de la línea donde se produjo la excepción.

previous

La anterior excepción utilizada para la excepción de encadenamiento.

Historial de cambios

VersiónDescripción
5.3.0El parámetropreviousfue añadido.



ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverityObtiene la severidad de la excepción

Descripción

finalpublicErrorException::getSeverity():int

Devuelve la severidad de la excepción.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nivel de la severidad de la excepción.

Ejemplos

Ejemplo #1 Ejemplo deErrorException::getSeverity()

<?php
try {
throw new
ErrorException("Mensaje de la excepción",0,E_USER_ERROR);
} catch(
ErrorException $e) {
echo
"La severidad de la excepción es: ".$e->getSeverity();
var_dump($e->getSeverity() ===E_USER_ERROR);
}
?>

El resultado del ejemplo sería algo similar a:

La severidad de la excepción es: 256
bool(true)


Tabla de contenidos



Error

(PHP 7, PHP 8)

Introducción

Errores la clase base para todos los errores de PHP internos.

Sinopsis de la Clase

classErrorimplementsThrowable{
/* Propiedades */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos */
public__construct(string$message= "",int$code= 0,Throwable$previous=null)
finalpublicgetMessage():string
finalpublicgetPrevious():Throwable
finalpublicgetCode():mixed
finalpublicgetFile():string
finalpublicgetLine():int
finalpublicgetTrace():array
finalpublicgetTraceAsString():string
public__toString():string
finalprivate__clone():void
}

Propiedades

message

El mensaje de error

code

El código de error

file

El nombre del fichero donde ocurrió el error

line

La línea donde ocurrió el error


Error::__construct

(PHP 7, PHP 8)

Error::__constructConstruir el objeto error

Descripción

publicError::__construct(string$message= "",int$code= 0,Throwable$previous=null)

Construye el Error.

Parámetros

message

El mensaje de error.

code

El código de error.

previous

El objeto Throwable anterior empleado para la cadena de excepciones.

Notas

Nota:

El parámetromessageNOes seguro a nivel binario.



Error::getMessage

(PHP 7, PHP 8)

Error::getMessageObtener el mensaje de error

Descripción

finalpublicError::getMessage():string

Devuelve el mensaje de error.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el mensaje de error como una cadena.

Ejemplos

Ejemplo #1 Ejemplo deError::getMessage()

<?php
try {
throw new
Error("Un mensaje de error");
} catch(
Error $e) {
echo
$e->getMessage();
}
?>

El resultado del ejemplo sería algo similar a:

Un mensaje de error

Ver también



Error::getPrevious

(PHP 7, PHP 8)

Error::getPreviousDevuelve el objeto Throwable anterior

Descripción

finalpublicError::getPrevious():Throwable

Devuelve el objeto Throwable anterior (el tercer parámetro deError::__construct()).

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el objetoThrowableanterior si está disponible, onullen caso contrario.

Ejemplos

Ejemplo #1 Ejemplo deError::getPrevious()

Recorrer e imprimir la traza de errores.

<?php
classMiErrorPersonalizadoextendsError{}

function
hacerCosas() {
try {
throw new
InvalidArgumentError("¡Lo está haciendo mal!",112);
} catch(
Error $e) {
throw new
MiErrorPersonalizado("Ocurrió algo",911,$e);
}
}


try {
hacerCosas();
} catch(
Error $e) {
do {
printf("%s:%d %s (%d) [%s]\n",$e->getFile(),$e->getLine(),$e->getMessage(),$e->getCode(),get_class($e));
} while(
$e=$e->getPrevious());
}
?>

El resultado del ejemplo sería algo similar a:

/home/bjori/ex.php:8 Ocurrió algo (911) [MiErrorPersonalizado]
/home/bjori/ex.php:6 ¡Lo está haciendo mal! (112) [InvalidArgumentError]

Ver también



Error::getCode

(PHP 7, PHP 8)

Error::getCodeObtener el código de error

Descripción

finalpublicError::getCode():mixed

Devuelve el código de error.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el código de error como uninteger

Ejemplos

Ejemplo #1 Ejemplo deError::getCode()

<?php
try {
throw new
Error("Un mensaje de error",30);
} catch(
Error $e) {
echo
"El código del Error es: ".$e->getCode();
}
?>

El resultado del ejemplo sería algo similar a:

El código del Error es: 30

Ver también



Error::getFile

(PHP 7, PHP 8)

Error::getFileObtener el fichero en el que ocurrío el error

Descripción

finalpublicError::getFile():string

Obtiene el nombre del fichero donde ocurrió el error.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre del fichero el en cual ocurrió el error.

Ejemplos

Ejemplo #1 Ejemplo deError::getFile()

<?php
try {
throw new
Error;
} catch(
Error $e) {
echo
$e->getFile();
}
?>

El resultado del ejemplo sería algo similar a:

/home/bjori/tmp/ex.php

Ver también



Error::getLine

(PHP 7, PHP 8)

Error::getLineObtener la línea en la que ocurrió el error

Descripción

finalpublicError::getLine():int

Obtiene el número de línea donde ocurrió el error.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el número de línea en la que ocurrió el error.

Ejemplos

Ejemplo #1 Ejemplo deError::getLine()

<?php
try {
throw new
Error("Un mensaje de error");
} catch(
Error $e) {
echo
"El error se ocasionó en la línea: ".$e->getLine();
}
?>

El resultado del ejemplo sería algo similar a:

El error se ocasionó en la línea: 3

Ver también



Error::getTrace

(PHP 7, PHP 8)

Error::getTraceObtener la traza de la pila

Descripción

finalpublicError::getTrace():array

Devuelve la traza de la pila.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la traza de la pila como unarray.

Ejemplos

Ejemplo #1 Ejemplo deError::getTrace()

<?php
functionprueba() {
throw new
Error;
}

try {
prueba();
} catch(
Error $e) {
var_dump($e->getTrace());
}
?>

El resultado del ejemplo sería algo similar a:

array(1) {
  [0]=>
  array(4) {
    ["file"]=>
    string(22) "/home/bjori/tmp/ex.php"
    ["line"]=>
    int(7)
    ["function"]=>
    string(6) "prueba"
    ["args"]=>
    array(0) {
    }
  }
}

Ver también



Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsStringObtener la traza de la pila como un string

Descripción

finalpublicError::getTraceAsString():string

Devuelve la traza de la pila como un string.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la traza de la pila como un string.

Ejemplos

Ejemplo #1 Ejemplo deError::getTraceAsString()

<?php
functionprueba() {
throw new
Error;
}

try {
prueba();
} catch(
Error $e) {
echo
$e->getTraceAsString();
}
?>

El resultado del ejemplo sería algo similar a:

#0 /home/bjori/tmp/ex.php(7): prueba()
#1 {main}

Ver también



Error::__toString

(PHP 7, PHP 8)

Error::__toStringRepresentación de string del error

Descripción

publicError::__toString():string

Devuelve la representación destringdel error.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la representación destringdel error.

Ejemplos

Ejemplo #1 Ejemplo deError::__toString()

<?php
try {
throw new
Error("Un mensaje de error");
} catch(
Error $e) {
echo
$e;
}
?>

El resultado del ejemplo sería algo similar a:

Error: Un mensaje de error in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}

Ver también



Error::__clone

(PHP 7, PHP 8)

Error::__cloneClonar el error

Descripción

finalprivateError::__clone():void

Un error no se pueden clonar, por lo que este método resulta en un error fatal.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Los erroresnoson clonabes.


Tabla de contenidos



ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

Introducción

ArgumentCountErrores lanzado cuando muy pocos argumentos son pasados a una funcion o método definido por el usuario.

Sinopsis de la Clase

classArgumentCountErrorextendsTypeError{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
finalpublicError::getMessage():string
finalpublicError::getCode():mixed
finalpublicError::getFile():string
finalpublicError::getLine():int
finalpublicError::getTrace():array
finalpublicError::getTraceAsString():string
publicError::__toString():string
finalprivateError::__clone():void
}


ArithmeticError

(PHP 7, PHP 8)

Introducción

UnArithmeticErrores lanzado cuando ocurre un error durante la realización de operaciones matemáticas. En PHP 7.0, estos errores incluyen el intento de realizar un desplazamiento de bit mediante una cantidad negativa, y cualquier llamada aintdiv()que resulte en un valor fuera de los límites posibles de uninteger.

Sinopsis de la Clase

classArithmeticErrorextendsError{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
finalpublicError::getMessage():string
finalpublicError::getCode():mixed
finalpublicError::getFile():string
finalpublicError::getLine():int
finalpublicError::getTrace():array
finalpublicError::getTraceAsString():string
publicError::__toString():string
finalprivateError::__clone():void
}


AssertionError

(PHP 7, PHP 8)

Introducción

UnAssertionErrorse lanza cuando falla una afirmación realizada medianteassert().

Sinopsis de la Clase

classAssertionErrorextendsError{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
finalpublicError::getMessage():string
finalpublicError::getCode():mixed
finalpublicError::getFile():string
finalpublicError::getLine():int
finalpublicError::getTrace():array
finalpublicError::getTraceAsString():string
publicError::__toString():string
finalprivateError::__clone():void
}


DivisionByZeroError

(PHP 7, PHP 8)

Introducción

UnDivisionByZeroErrorse lanza al intentar dividir un número por cero.

Sinopsis de la Clase

classDivisionByZeroErrorextendsArithmeticError{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
finalpublicError::getMessage():string
finalpublicError::getCode():mixed
finalpublicError::getFile():string
finalpublicError::getLine():int
finalpublicError::getTrace():array
finalpublicError::getTraceAsString():string
publicError::__toString():string
finalprivateError::__clone():void
}


CompileError

(PHP 7 > 7.3.0, PHP 8)

Introducción

CompileErrores lanzado por algunos errores de compilación, que anteriormente emitió un error fatal.

Sinopsis de la Clase

classCompileErrorextendsError{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
finalpublicError::getMessage():string
finalpublicError::getCode():mixed
finalpublicError::getFile():string
finalpublicError::getLine():int
finalpublicError::getTrace():array
finalpublicError::getTraceAsString():string
publicError::__toString():string
finalprivateError::__clone():void
}


ParseError

(PHP 7, PHP 8)

Introducción

UnParseErrorse lanza cuando ocurre un error al analizar código de PHP, tal como cuando se llama aeval().

Nota:ParseErrorextiendeCompileErrora partir de PHP 7.3.0. Anteriormente, extendíaError.

Sinopsis de la Clase

classParseErrorextendsCompileError{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
finalpublicError::getMessage():string
finalpublicError::getCode():mixed
finalpublicError::getFile():string
finalpublicError::getLine():int
finalpublicError::getTrace():array
finalpublicError::getTraceAsString():string
publicError::__toString():string
finalprivateError::__clone():void
}


TypeError

(PHP 7, PHP 8)

Introducción

Existen tres escenarios donde de podría lanzar unTypeError. El primero es donde el tipo de argumento pasado a una función no coincide con su correspondiente tipo de parámetro declarado. El segundo es donde un valor devuelto desde una función no coincide con el tipo de devolución declarado en la función. El tercero es donde se proporciona un número inválido de argumentos a una función interna de PHP (solamente en modo estricto).

Sinopsis de la Clase

classTypeErrorextendsError{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
finalpublicError::getMessage():string
finalpublicError::getCode():mixed
finalpublicError::getFile():string
finalpublicError::getLine():int
finalpublicError::getTrace():array
finalpublicError::getTraceAsString():string
publicError::__toString():string
finalprivateError::__clone():void
}



Interfaces y clases predefinidas

Tabla de contenidos

Véanse también lasinterfaces de la SPLy lasclases reservadas.


La interfazTraversable

(PHP 5, PHP 7, PHP 8)

Introducción

Interfaz para detectar si una clase puede recorrerse medianteforeach.

Una interfaz abstracta base no puede ser implementada sola. En su lugar, debe ser implementada conIteratorAggregateo conIterator.

Nota:

Las clases internas que implementan esta interfaz pueden ser usadas en una construcciónforeachy no necesitan implementarIteratorAggregateoIterator.

Nota:

Esta es una interfaz del motor interno que no puede ser implementada en scripts de PHP. Se debe emplear en su lugar oIteratorAggregate, o bienIterator. Cuando se implementa una interfaz que extiende a Traversable, asegúrese de enumerarIteratorAggregateoIteratorantes de su nombre en la cláusula de implementación.

Sinopsis de la Interfaz

classTraversable{
}

Esta interfaz no tiene métodos; su único propósito es servir de interfaz base para todas las clases que se pueden recorrer.



La interfaz Iterator

(PHP 5, PHP 7, PHP 8)

Introducción

Interfaz para iteradores externos u objetos que pueden ser iterados internamente por sí mismos.

Sinopsis de la Interfaz

classIteratorextendsTraversable{
/* Métodos */
abstractpubliccurrent():mixed
abstractpublickey():scalar
abstractpublicnext():void
abstractpublicrewind():void
abstractpublicvalid():bool
}

Iteradores Predefinidos

PHP ya ofrece un número de iteradores para muchas de las tareas del día a día. Véase la lista deiteradores SPL.

Ejemplos

Ejemplo #1 Uso básico

Este ejemplo muestra el orden en el que se llaman a los métodos cuando se emplea unforeachcon un iterator.

<?php
classmyIteratorimplementsIterator{
private
$position=0;
private
$array= array(
"firstelement",
"secondelement",
"lastelement",
);

public function
__construct() {
$this->position=0;
}

public function
rewind() {
var_dump(__METHOD__);
$this->position=0;
}

public function
current() {
var_dump(__METHOD__);
return
$this->array[$this->position];
}

public function
key() {
var_dump(__METHOD__);
return
$this->position;
}

public function
next() {
var_dump(__METHOD__);
++
$this->position;
}

public function
valid() {
var_dump(__METHOD__);
return isset(
$this->array[$this->position]);
}
}

$it= newmyIterator;

foreach(
$itas$key=>$value) {
var_dump($key,$value);
echo
"\n";
}
?>

El resultado del ejemplo sería algo similar a:

string(18) "myIterator::rewind"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(0)
string(12) "firstelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(1)
string(13) "secondelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(2)
string(11) "lastelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"

Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::currentDevuelve el elemento actual

Descripción

abstractpublicIterator::current():mixed

Devuelve el elemento actual.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Puede devolver cualquier tipo.



Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::keyDevuelve la clave del elemento actual

Descripción

abstractpublicIterator::key():scalar

Devuelve la clave del elemento actual.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvescalaren caso de éxito, onullen caso de error.

Errores/Excepciones

Muestra unE_NOTICEen caso de error.



Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::nextAvanza al siguiente elemento

Descripción

abstractpublicIterator::next():void

Avanza la posición actual al siguiente elemento.

Nota:

El método es llamadodespuésde cadaforeachloop.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

El valor devuelto es ignorado.



Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewindRebobine la Iterator al primer elemento

Descripción

abstractpublicIterator::rewind():void

Rebobina de nuevo al primer elemento de la Iterator.

Nota:

Este es elprimermétodo llamado cuando se inicia unforeachbucle.Nova a ser ejecutadodespuesforeachbucle.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Cualquier valor devuelto se pasa por alto.



Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::validComprueba si la posición actual es válido

Descripción

abstractpublicIterator::valid():bool

Este método se llama después deIterator::rewind()yIterator::next()para comprobar si la posición actual es válido.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

El valor de retorno se debe fundir abooleany luego evaluar. Devuelvetrueen caso de éxito ofalseen caso de error.


Tabla de contenidos



La interfaz IteratorAggregate

(PHP 5, PHP 7, PHP 8)

Introducción

Para crear una interfaz externa Iterator.

Sinopsis de la Interfaz

classIteratorAggregateextendsTraversable{
/* Métodos */
abstractpublicgetIterator():Traversable
}

Ejemplo #1 Uso básico

<?php
classmyDataimplementsIteratorAggregate{
public
$property1="Public property one";
public
$property2="Public property two";
public
$property3="Public property three";

public function
__construct() {
$this->property4="last property";
}

public function
getIterator() {
return new
ArrayIterator($this);
}
}

$obj= newmyData;

foreach(
$objas$key=>$value) {
var_dump($key,$value);
echo
"\n";
}
?>

El resultado del ejemplo sería algo similar a:

string(9) "property1"
string(19) "Public property one"

string(9) "property2"
string(19) "Public property two"

string(9) "property3"
string(21) "Public property three"

string(9) "property4"
string(13) "last property"


IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIteratorRecuperar un Iterator externo

Descripción

abstractpublicIteratorAggregate::getIterator():Traversable

Devuelve un iterador externo.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Una instancia de un objeto que implementaIteratoroTraversable

Errores/Excepciones

Lanza unaExceptionen caso de fallo.


Tabla de contenidos



Throwable

(PHP 7, PHP 8)

Introducción

Throwablees la interfaz base para cualquier objeto que pueda ser lanzado mediante una sentenciathrowen PHP 7, incluyendoErroryException.

Nota:

Las clases de PHP no pueden implementar la interfazThrowabledirectamente, por lo que deben extender en su lugarException.

Sinopsis de la Interfaz

classThrowable{
/* Métodos */
abstractpublicgetMessage():string
abstractpublicgetCode():int
abstractpublicgetFile():string
abstractpublicgetLine():int
abstractpublicgetTrace():array
abstractpublicgetTraceAsString():string
abstractpublicgetPrevious():Throwable
abstractpublic__toString():string
}

Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessageObtiene el mensaje

Descripción

abstractpublicThrowable::getMessage():string

Devuelve el mensaje asociado al objeto lanzado.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el mensaje asociado al objeto lanzado.

Ver también



Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCodeObtener el código de la excepción

Descripción

abstractpublicThrowable::getCode():int

Devuelve el código de error asociado al objeto lanzado.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el código de la excepción como unintegerenException, aunque posiblemente como otro tipo en los descendientes deException(por ejemplo, comostringenPDOException).

Ver también



Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFileObtiene el fichero en el que se creó el objeto

Descripción

abstractpublicThrowable::getFile():string

Obtiene el nombre del fichero en el que se creó el objeto lanzado.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre del fichero en el que se creó la el objeto lanzado.

Ver también



Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLineObtiene la línea en la que el objeto fue instanciado

Descripción

abstractpublicThrowable::getLine():int

Devuelve el número de línea en la que el objeto fue instanciado.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el número de línea en la que el objeto fue instanciado.

Ver también



Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTraceObtener la traza de la pila

Descripción

abstractpublicThrowable::getTrace():array

Devuelve la traza de la pila como unarray.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la traza de la pila como unarraycon el mismo formato que endebug_backtrace().

Ver también



Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsStringObtener la traza de la pila como un string

Descripción

abstractpublicThrowable::getTraceAsString():string

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la traza de la pila como un string.

Ver también



Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPreviousDevuelve el objeto Throwable previo

Descripción

abstractpublicThrowable::getPrevious():Throwable

Devuelve el objeto Throwable previo (por ejemplo, uno proporcionado como tercer parámetro deException::__construct()).

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el objetoThrowableanterior si está disponible, onullsi no lo está.

Ver también



Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toStringObtiene un representación de string del objeto lanzado

Descripción

abstractpublicThrowable::__toString():string

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la representación destringdel objeto lanzado.

Ver también


Tabla de contenidos



La interfaz ArrayAccess

(PHP 5, PHP 7, PHP 8)

Introducción

Interfaz para proporcionar acceso a objetos como arrays.

Sinopsis de la Interfaz

classArrayAccess{
/* Métodos */
abstractpublicoffsetExists(mixed$offset):bool
abstractpublicoffsetGet(mixed$offset):mixed
abstractpublicoffsetSet(mixed$offset,mixed$value):void
abstractpublicoffsetUnset(mixed$offset):void
}

Ejemplo #1 Uso básico

<?php
classObjimplementsArrayAccess{
private
$contenedor= array();

public function
__construct() {
$this->contenedor= array(
"uno"=>1,
"dos"=>2,
"tres"=>3,
);
}

public function
offsetSet($offset,$valor) {
if (
is_null($offset)) {
$this->contenedor[] =$valor;
} else {
$this->contenedor[$offset] =$valor;
}
}

public function
offsetExists($offset) {
return isset(
$this->contenedor[$offset]);
}

public function
offsetUnset($offset) {
unset(
$this->contenedor[$offset]);
}

public function
offsetGet($offset) {
return isset(
$this->contenedor[$offset]) ?$this->contenedor[$offset] :null;
}
}

$obj= newObj;

var_dump(isset($obj["dos"]));
var_dump($obj["dos"]);
unset(
$obj["dos"]);
var_dump(isset($obj["dos"]));
$obj["dos"] ="Un valor";
var_dump($obj["dos"]);
$obj[] ='Añadido 1';
$obj[] ='Añadido 2';
$obj[] ='Añadido 3';
print_r($obj);
?>

El resultado del ejemplo sería algo similar a:

bool(true)
int(2)
bool(false)
string(8) "Un valor"
obj Object
(
    [contenedor:obj:private] => Array
        (
            [uno] => 1
            [tres] => 3
            [dos] => Un valor
            [0] => Añadido 1
            [1] => Añadido 2
            [2] => Añadido 3
        )

)

ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExistsComprobar si existe un índice

Descripción

abstractpublicArrayAccess::offsetExists(mixed$offset):bool

Comprueba si existe o no un índice.

Este método se ejecuta cuando se utilizan las funcionesisset()oempty()sobre los objetos que implementanArrayAccess.

Nota:

Cuando se utilizaempty(),ArrayAccess::offsetGet()será invocada para comprobar si está vacío solamente siArrayAccess::offsetExists()devuelvetrue.

Parámetros

offset

El índice a comprobar.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Nota:

El valor de retorno se debe convertir abooleansi no devuelve un valor boleano.

Ejemplos

Ejemplo #1 Ejemplo deArrayAccess::offsetExists()

<?php
classobjimplementsarrayaccess{
public function
offsetSet($offset,$value) {
var_dump(__METHOD__);
}
public function
offsetExists($var) {
var_dump(__METHOD__);
if (
$var=="foobar") {
return
true;
}
return
false;
}
public function
offsetUnset($var) {
var_dump(__METHOD__);
}
public function
offsetGet($var) {
var_dump(__METHOD__);
return
"value";
}
}

$obj= newobj;

echo
"Runs obj::offsetExists()\n";
var_dump(isset($obj["foobar"]));

echo
"\nRuns obj::offsetExists() and obj::offsetGet()\n";
var_dump(empty($obj["foobar"]));

echo
"\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
var_dump(empty($obj["foobaz"]));
?>

El resultado del ejemplo sería algo similar a:

Runs obj::offsetExists()
string(17) "obj::offsetExists"
bool(true)

Runs obj::offsetExists() and obj::offsetGet()
string(17) "obj::offsetExists"
string(14) "obj::offsetGet"
bool(false)

Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get
string(17) "obj::offsetExists"
bool(true)



ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGetOffset para recuperar

Descripción

abstractpublicArrayAccess::offsetGet(mixed$offset):mixed

Devuelve el valor correspondiente a desplazamiento especificado.

Este método se ejecuta para comprobar si el desplazamiento esempty().

Parámetros

offset

El desplazamiento va a recuperar.

Notas

Nota:

A partir de PHP 5.3.4, el prototipo de los controles se relajaron y es posible para las implementaciones de este método para devolver por referencia. Esto hace que las modificaciones indirectas a las dimensiones de los arreglos sobrecargados de objetosArrayAccessposibles.

Una modificación directa es aquella que reemplaza completamente el valor de la dimensión de el arreglo, como en$obj[6] = 7. Una modificación indirecta, por el contrario, sólo una parte los cambios de la dimensión, o los intentos de asignar la dimensión en función de otra variable, como en$obj[6][7] = 7o$var =& $obj[6]. Con incrementos++y disminye con--también se aplican de una manera que requiere la modificación indirecta.

Si bien la modificación directa desencadena una llamada aArrayAccess::offsetSet(), modificación indirecta provoca una llamada aArrayAccess::offsetGet(). En ese caso, la aplicación deArrayAccess::offsetGet()debe ser capaz de volver por la referencia, de lo contrario unE_NOTICEmensaje es elevado..

Valores devueltos

Puede devolver todos los tipos de valor.

Ver también



ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSetAsignar un valor al índice esepecificado

Descripción

abstractpublicArrayAccess::offsetSet(mixed$offset,mixed$value):void

Asigna un valor a un offset determinado.

Parámetros

offset

El offset al que se asigna el valor.

value

El valor a asignar.

Valores devueltos

No devuelve ningún valor.

Notas

Nota:

El parámetrooffsetserá inicializado anullsi otro valor no está disponible, como en el siguiente ejemplo.

<?php
$arrayaccess
[] ="primer valor";
$arrayaccess[] ="segundo valor";
print_r($arrayaccess);
?>

El resultado del ejemplo sería:

Array
(
    [0] => primer valor
    [1] => segundo valor
)

Nota:

Esta función no es invocada al realizar asignaciones por referencias y por tanto en los cambios de dimensiones en arrays sobrecargados conArrayAccess(indirecto en el sentido de que no se hace cambiando la dimensión directamente, sino cambiando una sub-dimensión o sub-propiedad o asignando la dimensión del array por referencia en otra variable). En su lugar, se llama aArrayAccess::offsetGet(). La operación tendrá éxito si devuelve el valor por referencia, lo cuál sólo es posible desde PHP 5.3.4.



ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnsetDestruye un offset

Descripción

abstractpublicArrayAccess::offsetUnset(mixed$offset):void

Destruye un offset.

Nota:

Este métodonoserá llamado cuando se fuerza un tipo mediante(unset)

Parámetros

offset

El offset a destruir.

Valores devueltos

No devuelve ningún valor.


Tabla de contenidos



La interfaz Serializable

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Introducción

Interfaz para personalizar la serialización.

Las clases que implementan esta interfaz ya no admiten__sleep()ni__wakeup(). El método serialize se llama cuando una instancia requiere ser serializada. Esto no invoca a __destruct() ni tiene ningún efecto adicional a menos que se programe dentro del método. Cuando los datos son deserializados, la clase es conocida y se llama al correspondiente método unserialize() como constructor en lugar de llamar al método __construct(). Se puede ejecutar el constructor estándar en el método si fuera necesario.

Sinopsis de la Interfaz

classSerializable{
/* Métodos */
abstractpublicserialize():string
abstractpublicunserialize(string$serialized):void
}

Ejemplo #1 Uso básico

<?php
classobjimplementsSerializable{
private
$datos;
public function
__construct() {
$this->datos="Mis datos privados";
}
public function
serialize() {
return
serialize($this->datos);
}
public function
unserialize($datos) {
$this->datos=unserialize($datos);
}
public function
getDatos() {
return
$this->datos;
}
}

$obj= newobj;
$ser=serialize($obj);

var_dump($ser);

$obj_nuevo=unserialize($ser);

var_dump($obj_nuevo->getDatos());
?>

El resultado del ejemplo sería algo similar a:

string(38) "C:3:"obj":23:{s:15:"Mis datos privados";}"
string(15) "Mis datos privados"

Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serializeRepresentación en formato cadena de un objeto

Descripción

abstractpublicSerializable::serialize():string

Devuelve la representación de un objeto en formato string.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la representación de un objeto onull

Errores/Excepciones

Lanza unaExceptioncuando de devuelen otros tipos aparte de string ynull

Ver también



Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserializeConstruye el objeto

Descripción

abstractpublicSerializable::unserialize(string$serialized):void

Es llamado durante la unserialización del objeto.

Nota:

Este método actua como elconstructordel objeto. El método__construct()noserá llamado después de este método.

Parámetros

serialized

La representación en formato string de un objeto.

Valores devueltos

El valor devuelto por este método es ignorado.

Ver también


Tabla de contenidos



La clase Closure

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Introducción

Clase empleada para representarfunciones anónimas.

Las funciones anónimas, implementadas en PHP 5.3, producían objetos de este tipo. Este hecho solía ser considerado como un detalle de implementación, pero ahora puede confiarse en él. Desde PHP 5.4, esta clase tiene métodos que permiten más control sobre las funciones anónimas después de haber sido creadas.

Además de los métodos listados aquí, esta clase también posse un método__invoke. Está por consistencia con otras clases que implementan lallamada mágica, ya que este método no se usa para llamar a la función.

Sinopsis de la Clase

classClosure{
/* Métodos */
private__construct()
publicstaticbind(Closure$closure,object$newthis,mixed$newscope= "static"):Closure
publicbindTo(object$newthis,mixed$newscope= "static"):Closure
publiccall(object$newthis,mixed$...= ?):mixed
publicstaticfromCallable(callable$callable):Closure
}

Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__constructConstructor que anula la instanciación

Descripción

privateClosure::__construct()

Este método sólo existe para anular la instanciación de la claseClosure. Los objetos de esta clase se crean del modo descrito en la páginafunciones anónimas.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Este método no tiene un valor de retorno; simplemente emite un error (de tipoE_RECOVERABLE_ERROR).



Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindDuplicar un cierre con un objeto vinculado y ámbito de clase especificados

Descripción

publicstaticClosure::bind(Closure$closure,object$newthis,mixed$newscope= "static"):Closure

Este método es una versión estática deClosure::bindTo(). Véase la documentación de ese método para más información.

Parámetros

closure

La función anónima a vincular.

newthis

El objeto al que la función anónima dada debería ser vinculado, onullpara que el cierre sea desvinculado.

newscope

El ámbito de clase a la que asociar el cierre, o 'static' para mantener el actual. Si se proporciona un objeto, el tipo del mismo se usará en su lugar. Esto determina la visibilidad de métodos protegidos y privados del objeto vinculado. No se permite pasar (un objeto de) una clase interna a este parámetro.

Valores devueltos

Devuelve un nuevo objetoClosureofalseen caso de error

Historial de cambios

VersiónDescripción
7.0.0newscopeya no puede ser (un objeto de) una clase interna, lo que era posible antes de esta versión.

Ejemplos

Ejemplo #1 Ejemplo deClosure::bind()

<?php
classA{
private static
$sfoo=1;
private
$ifoo=2;
}
$cl1= static function() {
return
A::$sfoo;
};
$cl2= function() {
return
$this->ifoo;
};

$bcl1=Closure::bind($cl1,null,'A');
$bcl2=Closure::bind($cl2, newA(),'A');
echo
$bcl1(),"\n";
echo
$bcl2(),"\n";
?>

El resultado del ejemplo sería algo similar a:

1
2

Ver también



Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindToDuplicar el cierre con un objeto vinculado y ámbito de clase nuevos

Descripción

publicClosure::bindTo(object$newthis,mixed$newscope= "static"):Closure

Crea y devuelve una nuevafunción anónimacon el cuerpo y variables vinculadas como ésta, pero posiblemente con un objeto vinculado diferente y un nuevo ámbito de clase.

El "objeto vinculado" determina el valor que$thistendrá en el cuerpo de la función, y el "ámbito de clase" representa una clase que determina los miembros privados y protegidos a los que será capaz de acceder la función anónima. Concretamente, los miembros que serán visibles son los mismos que si la función anónima fuese un método de la clase dada como valor del parámetronewscope.

Los cierres estáticos no pueden tener ningún objeto vinculado (el valor del parámetronewthisdebería sernull), pero esta función puede, no obstante, usarse para cambiar su ámbito de clase.

Esta función se asegurará de que a un cierre no estático que tenga una instancia vinculada se le aplique un ámbito y viceversa. En este punto, los cierres no estáticos que le son dados un ámbito, excepto una instancianull, son hechos estáticos, y los cierres no estáticos y sin ámbito que le son dados una instancia no nula se les aplica un ámbito de clase no especificado.

Nota:

Si solamente se quieren duplicar las funciones anónimas, se puede usarcloningen su lugar.

Parámetros

newthis

El objeto al que la función anónima dada debería ser vinculado, onullpara que el cierre sea desvinculado.

newscope

El ámbito de la clase a la que se va a asociar el cierre, o 'static' para mantener el actual. Si se proporciona un objeto, el tipo del mismo se usará en su lugar. Esto determina la visibilidad de métodos protegidos y privados del objeto vinculado. No se permite pasar (un objeto de) una clase interna a este parémtro.

Valores devueltos

Devuelve el objetoClosurerecién creado ofalseen caso de error

Historial de cambios

VersiónDescripción
7.0.0newscopeya no puede ser (un objeto de) una clase interna, lo cual era posible antes de esta versión.

Ejemplos

Ejemplo #1 Ejemplo deClosure::bindTo()

<?php

classA{
function
__construct($val) {
$this->val=$val;
}
function
getClosure() {
//devuelve el cierre vinculado a este objeto y el ámbito
return function() { return$this->val; };
}
}

$ob1= newA(1);
$ob2= newA(2);

$cl=$ob1->getClosure();
echo
$cl(),"\n";
$cl=$cl->bindTo($ob2);
echo
$cl(),"\n";
?>

El resultado del ejemplo sería algo similar a:

1
2

Ver también



Closure::call

(PHP 7, PHP 8)

Closure::callVincula y llama al cierre

Descripción

publicClosure::call(object$newthis,mixed$...= ?):mixed

Vincula temporalmente el cierre anewthis, y lo llama con cualquier parámetro dado.

Parámetros

newthis

Elobjecta vincular al cierre mientras dure la llamada.

...

Cero o más parámetros, que serán dados como parámetros al cierre.

Valores devueltos

Devuelve el valor devuelto por el cierre.

Ejemplos

Ejemplo #1 Ejemplo deClosure::call()

<?php
classValor{
protected
$valor;

public function
__construct($valor) {
$this->valor=$valor;
}

public function
getValor() {
return
$this->valor;
}
}

$tres= newValor(3);
$cuatro= newValor(4);

$cierre= function ($delta) {var_dump($this->getValor() +$delta); };
$cierre->call($tres,4);
$cierre->call($cuatro,4);
?>

El resultado del ejemplo sería:

int(7)
int(8)


Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallableConvierte un 'callable' en un cierre

Descripción

publicstaticClosure::fromCallable(callable$callable):Closure

Crea y devuelve una nuevafunción anónimadesde elcallabledado empleando el ámbito actual. Este método comprueba sicallablees llamable en el ámbito actual, lanzando unTypeErrorsi no lo es.

Parámetros

callable

El «callable» a convertir.

Valores devueltos

Devuelve el recién creadoClosureo lanza unTypeErrorsicallableno es llamable en el ámbito actual.


Tabla de contenidos



La clase Generator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Introducción

Los objetosGeneratorson devueltos desdegeneradores.

Precaución

Los objetosGeneratorno pueden ser instanciados mediantenew.

Sinopsis de la Clase

classGeneratorimplementsIterator{
/* Métodos */
publiccurrent():mixed
publickey():mixed
publicnext():void
publicrewind():void
publicsend(mixed$value):mixed
publicthrow(Throwable$exception):mixed
publicvalid():bool
public__wakeup():void
}

Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::currentObtener el valor producido

Descripción

publicGenerator::current():mixed

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el valor producido.



Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturnObtener el valor devuelto de un generador

Descripción

publicGenerator::getReturn():mixed

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el valor devuelto del generador una vez ha finalizado su ejecución.

Ejemplos

Ejemplo #1 Ejemplo deGenerator::getReturn()

<?php

$gen
= (function() {
yield
1;
yield
2;

return
3;
})();

foreach (
$genas$val) {
echo
$val,PHP_EOL;
}

echo
$gen->getReturn(),PHP_EOL;

El resultado del ejemplo sería:

1
2
3



Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::keyObtener la clave generada

Descripción

publicGenerator::key():mixed

Obtiene la clave del valor generado.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la clave generada.

Ejemplos

Ejemplo #1 Ejemplo deGenerator::key()

<?php

functionGen()
{
yield
'key'=>'value';
}

$gen=Gen();

echo
"{$gen->key()}=>{$gen->current()}";

El resultado del ejemplo sería:

key => value



Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::nextContinua la ejecución del generador

Descripción

publicGenerator::next():void

Llamar aGenerator::next()tiene el mismo efecto que llamar aGenerator::send()connullcomo argumento.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.



Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewindRebobina el iterador

Descripción

publicGenerator::rewind():void

Si la iteración ya ha comenzado, lanzará una excepción.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.



Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::sendEnviar un valor al generador

Descripción

publicGenerator::send(mixed$value):mixed

Envía el valor dado al generador como resultado de la expresiónyieldactual y reanuda la ejecución del generador.

Si el generador no es una expresiónyielden el momento de invocar a este método, se permitirá avanzar a la primera expresiónyieldantes de enviar el valor. Por tanto, no es necesario «preparar» generadores de PHP con una llamada aGenerator::next()(como se hace en Python).

Parámetros

value

El valor a enviar al generador. Este valor será el valor devuelto de la expresiónyielden la que está actualmente el generador.

Valores devueltos

Devuelve el valor producido.

Ejemplos

Ejemplo #1 Empleo deGenerator::send()para inyectar valores

<?php
functionprinter() {
echo
"¡Soy una impresora!".PHP_EOL;
while (
true) {
$string= yield;
echo
$string;
}
}

$printer=printer();
$printer->send('¡Hola mundo!');
$printer->send('¡Adiós mundo!');
?>

El resultado del ejemplo sería:

¡Soy una impresora!
¡Hola mundo!
¡Adiós mundo!



Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throwLanzar una excepción dentro generador

Descripción

publicGenerator::throw(Throwable$exception):mixed

Lanza una excepción dentro del generador y reanuda su ejecución. El comportamiento será el mismo que si la expresiónyieldactual fuera reemplazada con una sentenciathrow $exception.

Si el generador ya está cerrado al invocar a este método, la excepción será lanzada en su lugar en el contexto del invocador.

Parámetros

exception

La excepción a lanzar dentro del generador.

Valores devueltos

Devuelve el valor generado.

Historial de cambios

VersiónDescripción
7.0.0Ahora el parámetroexceptiontambién aceptaThrowable.

Ejemplos

Ejemplo #1 Lanzar una ecepión dentro de un generador

<?php
functiongen() {
echo
"Foo\n";
try {
yield;
} catch (
Exception $e) {
echo
"Excepción:{$e->getMessage()}\n";
}
echo
"Bar\n";
}

$gen=gen();
$gen->rewind();
$gen->throw(newException('Prueba'));
?>

El resultado del ejemplo sería:

Foo
Excepción: Prueba
Bar



Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::validVerificar si el iterador ha sido cerrado

Descripción

publicGenerator::valid():bool

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvefalsesi el iterador ha sido cerrado. De lo contrario devuelvetrue.



Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeupSerialize callback

Descripción

publicGenerator::__wakeup():void

Lanza una excepción indicando que el generador no puede ser presentado.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.


Tabla de contenidos



La clase WeakReference

(PHP 7 >= 7.4.0, PHP 8)

Introducción

Las referencias débiles permiten al programador retener una referencia a un objeto que no impide que el objeto sea destruido. Son útiles para implementar estructuras de tipo cache.

WeakReferenceno puede ser serializado.

Sinopsis de la Clase

classWeakReference{
/* Métodos */
public__construct()
publicstaticcreate(object$referent):WeakReference
publicget():?object
}

Ejemplos de WeakReference

Ejemplo #1 Uso básico de WeakReference

<?php
$obj
= newstdClass;
$weakref=WeakReference::create($obj);
var_dump($weakref->get());
unset(
$obj);
var_dump($weakref->get());
?>

El resultado del ejemplo sería algo similar a:

object(stdClass)#1 (0) {
}
NULL


WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__constructConstructor que no permite la instanciación

Descripción

publicWeakReference::__construct()

Este método existe sólo para no permitir la instanciación de la claseWeakReference. Las referencias débiles deben ser instanciadas con el método factoryWeakReference::create().

Parámetros

Esta función no tiene parámetros.

Ver también



WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::createCrea una nueva referencia débil

Descripción

publicstaticWeakReference::create(object$referent):WeakReference

Crea una nuevaWeakReference.

Parámetros

referent

El objeto a ser referenciado débilmente.

Valores devueltos

Devuelve el objeto recién instanciado.



WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::getObtiene un objeto débilmente referenciado

Descripción

publicWeakReference::get():?object

Se obtiene un objeto débilmente referenciado. Si el objeto ya ha sido destruido, devuelvenull.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el referenciadoobject, onullsi el objeto ha sido destruido.


Tabla de contenidos




Predefined Attributes

Tabla de contenidos

PHP provides some predefined attributes that can be used.


The Attribute class

(PHP 8)

Introducción

Attributes offer the ability to add structured, machine-readable metadata information on declarations in code: Classes, methods, functions, parameters, properties and class constants can be the target of an attribute. The metadata defined by attributes can then be inspected at runtime using theReflection APIs. Attributes could therefore be thought of as a configuration language embedded directly into code.

Sinopsis de la Clase

finalclassAttribute{
/* Constantes */
constintTARGET_CLASS;
constintTARGET_METHOD;
constintTARGET_ALL;
constintIS_REPEATABLE;
/* Propiedades */
publicint$flags;
/* Métodos */
public__construct(int$flags= Attribute::TARGET_ALL)
}

Constantes predefinidas

Attribute::TARGET_CLASS

Attribute::TARGET_FUNCTION

Attribute::TARGET_METHOD

Attribute::TARGET_PROPERTY

Attribute::TARGET_CLASS_CONSTANT

Attribute::TARGET_PARAMETER

Attribute::TARGET_ALL

Attribute::IS_REPEATABLE

Propiedades

flags


Attribute::__construct

(PHP 8)

Attribute::__constructConstruct a new Attribute instance

Descripción

publicAttribute::__construct(int$flags= Attribute::TARGET_ALL)

Constructs a newAttributeinstance.

Parámetros

flags


Tabla de contenidos



The AllowDynamicProperties class

(PHP 8 >= 8.2.0)

Introducción

This attribute is used to mark classes that allowdynamic properties.

Sinopsis de la Clase

finalclassAllowDynamicProperties{
/* Métodos */
public__construct()
}

Ejemplos

Dynamic properties are deprecated as of PHP 8.2.0, thus using them without marking the class with this attribute will emit a deprecation notice.

<?php
classDefaultBehaviour{ }

#[\AllowDynamicProperties]
classClassAllowsDynamicProperties{ }

$o1= newDefaultBehaviour();
$o2= newClassAllowsDynamicProperties();

$o1->nonExistingProp=true;
$o2->nonExistingProp=true;
?>

Output of the above example in PHP 8.2:

Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10

AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__constructConstruct a new AllowDynamicProperties attribute instance

Descripción

publicAllowDynamicProperties::__construct()

Constructs a newAllowDynamicPropertiesinstance.

Parámetros

Esta función no tiene parámetros.


Tabla de contenidos



The ReturnTypeWillChange class

(PHP 8 >= 8.1.0)

Introducción

Most non-final internal methods now require overriding methods to declare a compatible return type, otherwise a deprecated notice is emitted during inheritance validation. In case the return type cannot be declared for an overriding method due to PHP cross-version compatibility concerns, a#[\ReturnTypeWillChange]attribute can be added to silence the deprecation notice.

Sinopsis de la Clase

finalclassReturnTypeWillChange{
/* Métodos */
public__construct()
}

ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__constructConstruct a new ReturnTypeWillChange attribute instance

Descripción

publicReturnTypeWillChange::__construct()

Constructs a newReturnTypeWillChangeinstance.

Parámetros

Esta función no tiene parámetros.


Tabla de contenidos



The SensitiveParameter class

(PHP 8 >= 8.2.0)

Introducción

This attribute is used to mark a parameter that is sensitive and should have its value redacted if present in a stack trace.

Sinopsis de la Clase

finalclassSensitiveParameter{
/* Métodos */
public__construct()
}

Ejemplos

<?php

functiondefaultBehavior(
string $secret,
string $normal
) {
throw new
Exception('Error!');
}

function
sensitiveParametersWithAttribute(
#[\SensitiveParameter]
string $secret,
string $normal
) {
throw new
Exception('Error!');
}

try {
defaultBehavior('password','normal');
} catch (
Exception $e) {
echo
$e,PHP_EOL,PHP_EOL;
}

try {
sensitiveParametersWithAttribute('password','normal');
} catch (
Exception $e) {
echo
$e,PHP_EOL,PHP_EOL;
}

?>

Output of the above example in PHP 8.2 is similar to:

Exception: Error! in example.php:7
Stack trace:
#0 example.php(19): defaultBehavior('password', 'normal')
#1 {main}

Exception: Error! in example.php:15
Stack trace:
#0 example.php(25): sensitiveParametersWithAttribute(Object(SensitiveParameterValue), 'normal')
#1 {main}

Ver también


SensitiveParameter::__construct

(PHP 8 >= 8.2.0)

SensitiveParameter::__constructConstruct a new SensitiveParameter attribute instance

Descripción

publicSensitiveParameter::__construct()

Constructs a newSensitiveParameterinstance.

Parámetros

Esta función no tiene parámetros.


Tabla de contenidos




Opciones y parámetros de contexto

PHP ofrece varias opciones y parámetros de contexto que pueden utilizarse con todos los sistemas de ficheros y envolturas de flujos. Un contexto se crea constream_context_create(). Las opciones se establecen constream_context_set_option(), y los parámetros constream_context_set_params().


Opciones de contexto de sockets

Opciones de contexto de socketsListado de opciones de contexto de sockets

Descripción

Las opciones de contexto de sockets están disponibles para todas las envolturas que trabajan sobre sockets, comotcp,httpyftp.

Opciones

bindto

Usada para especificar la dirección IP (ya sea IPv4 o IPv6) y/o el número de puerto que PHP usará para acceder a la red. La sintaxis esip:puertopara direcciones IPv4, y[ip]:puertopara direcciones IPv6. Establecer el número IP o de puerto como0producirá que el sistema lo elija por usted.

Nota:

Dado que FTP crea dos conexiones de socket durante la operación normal, no es posible especificar el número de puerto con esta opción.

backlog

Usado para limitar el número de conexiones pendientes en la cola de escucha del socket.

Nota:

Solamente se aplica astream_socket_server().

Historial de cambios

VersiónDescripción
5.3.3Se agregóbindto.
5.1.0Se agregóbacklog.

Ejemplos

Ejemplo #1 Ejemplo de uso básico debindto

<?php
// conectarse a internet usando la IP '192.168.0.100'
$opciones= array(
'socket'=> array(
'bindto'=>'192.168.0.100:0',
),
);


// conectarse a internet usando la IP '192.168.0.100' y el puerto '7000'
$opciones= array(
'socket'=> array(
'bindto'=>'192.168.0.100:7000',
),
);


// conectarse a internet usando la dirección IPv6 '2001:db8::1'
// y el puerto '7000'
$opciones= array(
'socket'=> array(
'bindto'=>'[2001:db8::1]:7000',
),
);


// conectarse a internet usando el puerto '7000'
$opciones= array(
'socket'=> array(
'bindto'=>'0:7000',
),
);


// crear el contexto...
$contexto=stream_context_create($opciones);

// ...y usarlo para recuperar los datos
echofile_get_contents('http://www.example.com',false,$contexto);

?>



Opciones de contexto de HTTP

Opciones de contexto de HTTPListado de opciones de contexto de HTTP

Descripción

Opciones de contexto para los transporteshttp://yhttps://.

Opciones

methodstring

GET,POST, o cualquier otro método HTTP que admita el servidor remoto.

Por omisión,GET.

headerstring

Las cabeceras adicionales que se envían en la petición. Los valores de esta opción sobrescribirán los existentes (tales comoUser-agent:,Host:, oAuthentication:).

user_agentstring

Valor de la cabeceraUser-Agent:. Solo se utilizará si el agentenose ha especificado en la opción de contextoheadervista arriba.

Por omisión, se utiliza el valor del ajusteuser_agentdephp.ini.

contentstring

Datos adicionales a enviar tras las cabeceras. Típicamente se utiliza con peticiones POST o PUT.

proxystring

El URI que define la dirección de un servidor proxy (p.ej.tcp://proxy.example.com:5100).

request_fulluriboolean

Cuando se establece atrue, se utilizará todo el URI para construir la petición, (es decir,GET http://www.example.com/path/to/file.html HTTP/1.0). A pesar de que es un formato de petición no estándar, algunos servidores proxy requieren que sea así.

Por omisión esfalse.

follow_locationinteger

Seguir las redirecciones de las cabecerasLocation. Establecer a0para deshabilitarlo.

Por omisión es1.

max_redirectsinteger

El número máximo de redirecciones a seguir. Un valor igual o menor a1indica que no se siga ninguna redirección.

Por omisión es20.

protocol_versionfloat

La versión del protocolo HTTP.

Por omisión es1.0.

Nota:

Las versiónes de PHP anteriores a la 5.3.0 no implementan la decodificación de transferencias fragmentadas. Si este valor es1.1, es responsabilidad del programador cumplir con la versión1.1.

timeoutfloat

El tiempo de espera de lectura en segundos, especificado por unfloat(p.ej.10.5).

Por omisión, se utiliza el valor del ajustedefault_socket_timeoutdephp.ini.

ignore_errorsboolean

Obtener el contenido incluso con códigos de estado de error.

Por omisión esfalse.

Historial de cambios

VersiónDescripción
5.3.4Se añadiófollow_location.
5.3.0La opciónprotocol_versionadmite la decodificación de transferencias fragmentadas en caso de valer1.1.
5.2.10Se añadióignore_errors.
5.2.10El parámetroheaderahora puede ser unarrayde índices numéricos.
5.2.1Se añadiótimeout.
5.1.0Se añadió el soporte de HTTPS mediante proxies HTTP.
5.1.0Se añadiómax_redirects.
5.1.0Se añadióprotocol_version.

Ejemplos

Ejemplo #1 Obtener una página y enviar datos POST

<?php

$datos_post
=http_build_query(
array(
'var1'=>'contenido',
'var2'=>'doh'
)
);

$opciones= array('http'=>
array(
'method'=>'POST',
'header'=>'Content-type: application/x-www-form-urlencoded',
'content'=>$datos_post
)
);

$contexto=stream_context_create($opciones);

$resultado=file_get_contents('http://example.com/submit.php',false,$contexto);

?>

Ejemplo #2 Ignorar las redirecciones, aunque obtener las cabeceras y el contenido

<?php

$url
="http://www.example.org/header.php";

$opciones= array('http'=>
array(
'method'=>'GET',
'max_redirects'=>'0',
'ignore_errors'=>'1'
)
);

$contexto=stream_context_create($opciones);
$flujo=fopen($url,'r',false,$contexto);

// información de cabeceras y meta datos
// sobre el flujo
var_dump(stream_get_meta_data($flujo));

// datos reales en $url
var_dump(stream_get_contents($flujo));
fclose($flujo);
?>

Notas

Nota:Opciones de contexto del flujo de socket subyacente
Se pueden admitir opciones de contexto adicionales mediante eltransporte subyacente. Para flujoshttp://, deben consultarse las opciones de contexto del transportetcp://. Para flujoshttps://, deben consultarse las opciones de contexto del transportessl://.

Nota:Línea de estado HTTP
Cuando esta envultura de flujo sigue una redirección, los datos enwrapper_datadevueltos porstream_get_meta_data()podrían no contener necesariamente la línea de estado HTTP que realmente se aplica a los datos del contenido del índice0.

array (
  'wrapper_data' =>
  array (
    0 => 'HTTP/1.0 301 Moved Permantenly',
    1 => 'Cache-Control: no-cache',
    2 => 'Connection: close',
    3 => 'Location: http://example.com/foo.jpg',
    4 => 'HTTP/1.1 200 OK',
    ...
La primera petición devolvió un301(redirección permanente), de manera que la envoltura del flujo sigue automáticamente la redirección para obtener una respuesta de código200(índice =4).



Opciones de contexto para FTP

Opciones de contexto para FTPListado de opciones de contexto para FTP

Descripción

Opciones de contexto para transportesftp://yftps://

Opciones

overwriteboolean

Permite sobrescribir archivos ya existentes en el servidor remoto. Se aplica sólo al modo de escritura (subida).

Defaults tofalse.

resume_posinteger

Desplazamiento de archivo en donde iniciar la transferencia. Se aplica sólo al modo de lectura (descarga).

Por defecto es0(inicio del archivo).

proxystring

Petición FTP al proxy por medio de un servidor proxy http. Se aplica sólo a operaciones de lectura de archivos. Ejemplo:tcp://squid.example.com:8000.

Historial de cambios

VersiónDescripción
5.1.0Se añadióproxy.

Notas

Nota:Opciones subyacentes del contexto del flujo del socket
Opciones adicionales de contexto pueden se soportadas por eltransporte subyacentePara flujosftp://, remitirse a las opciones de contexto para el transportetcp://. Para flujosftps://, remitirse a las opciones de contexto para el transportessl://.



Opciones de contexto para SSL

Opciones de contexto para SSLListado de opciones de contexto para SSL

Descripción

Opciones de contexto para transportesssl://ytls://

Opciones

peer_namestring

Nombre del par a utilizar. Si no se establece este valor, se averigua basándose en el nombre del host empleado al abrir el flujo.

verify_peerboolean

Requerir verificación del certificado SSL utilizado.

Por defecto estrue.

verify_peer_nameboolean

Requerir verificación de nombre del par.

Por defecto estrue.

allow_self_signedboolean

Permite certificados auto-firmados. Requiereverify_peer.

Por defecto esfalse

cafilestring

Ubicación del archivo de la entidad emisora de certificados en el sistema de archivos local, la cual debe ser utilizada con la opción de contextoverify_peerpara autenticar la identidad del par remoto.

capathstring

Si no se específicacafileo si no se encuentra el certificado, el directorio al que apuntacapathsera explorado en busca de un certificado apropiado.capathdebe ser un directorio con el hash correcto.

local_certstring

Ruta hacia el archivo del certificado local en el sistema de archivos. Debe ser un archivo codificado con PEM el cual contenga el certificado y la llave privada. Puede, opcionalmente, contener la cadena de los emisores del certificado. La clave privada también podría estar contenida en un fichero aparte especificado porlocal_pk.

local_pkstring

Ruta a fichero de clave privada local del sistema de ficheros en caso ficheros separados para el certificado (local_cert) y la clave privada.

passphrasestring

La frase de contraseña con la cual el archivolocal_certfue codificado.

CN_matchstring

El nombre común que se está esperando. PHP realizará comparaciones limitadas de comodines. Si el nombre común no coincide con esto, el intento de conexión fallará.

Nota:Esta opción está obsoleta a favor depeer_name, a partir de PHP 5.6.0.

verify_depthinteger

Abortar si la cadena de certificados es demasiado profunda.

Por defecto es no verificarlo.

ciphersstring

Establece la lista de sistemas de cifrado disponibles. El formato de la cadena se describe en» ciphers(1).

Por defecto esDEFAULT.

capture_peer_certboolean

Si se establece entrue, una opción de contextopeer_certificateserá creada, conteniendo el certificado par.

capture_peer_cert_chainboolean

Si se establece entrue, una opción de contextopeer_certificate_chainserá creada, conteniendo la cadena del certificado.

SNI_enabledboolean

Si se establece entrue, la indicación del nombre del servidor se activará. Activando SNI se permiten múltiples certificados en la misma dirección IP.

SNI_server_namestring

Si se establece, entonces este valor se utilizará como nombre del servidor para la indicación de nombre de servidor. Si este valor no está establecido, entonces el nombre del servidor se supone basado en el nombre de host utilizado cuando se abre el flujo.

Nota:Esta opción está obsoleta a favor depeer_name, a partir de PHP 5.6.0.

disable_compressionboolean

Si está establecido, deshabilita la comprensión TLS. Esto puede ayudar a mitigar el vector de ataque CRIME.

peer_fingerprintstring|array

Aborta cuando el resumen del certificado remoto no coincide con el has especificado.

Cuando se emplea unstring, la longitud determinará qué algoritmo hash se aplica, si "md5" (32) o "sha1" (40).

Cuando se emplea unarray, las claves indican el nombre del algoritmo hash y cada valor correspondiente es el resumen previsto.

Historial de cambios

VersiónDescripción
5.6.0Se añadieronpeer_fingerprintandverify_peer_name. El valor predeterminado deverify_peerse cambió atrue.
5.4.13Se añadiódisable_compression. Requiere OpenSSL >= 1.0.0.
5.3.2Se añadióSNI_enabledySNI_server_name.

Notas

Nota:Debido a quessl://el es transporte subyacente para las envolturashttps://yftps://, cualquier opción de contexto que aplique parassl://también aplica parahttps://yftps://.

Nota:Para que SNI (Server Name Indication) esté disponible, entonces PHP se debe compilar con OpenSSL 0.9.8j o superior. Se utilizaOPENSSL_TLSEXT_SERVER_NAMEpara determinar si SNI está soportado.



Opciones de contexto para CURL

Opciones de contexto para CURLListado de opciones de contexto para CURL

Descripción

Las opciones de contexto para CURL están disponibles cuando la extensiónCURLfue compilada usando la opción de configuración--with-curlwrappers.

Opciones

methodstring

GET,POST, o cualquier otro método HTTP soportado por el servidor remoto.

Por defecto esGET.

headerstring

Cabeceras adicionales a ser enviadas durante la petición. Los valores de esta opción sobrescribirán otros valores (como por ejemploUser-agent:,Host:, yAuthentication:).

user_agentstring

Valor a ser enviado con la cabecera User-Agent:.

Por defecto se usa la configuraciónuser_agentdephp.ini.

contentstring

Datos adicionales para ser enviados después de las cabeceras. Esta opción no se utiliza para peticionesGEToHEAD.

proxystring

URI que especifica la dirección del servidor proxy. (Por ejemplotcp://proxy.example.com:5100).

max_redirectsinteger

El número máximo de redirecciones a seguir. Un valor de1o menos significa que no se siguen la redirecciones.

Por defecto es20.

curl_verify_ssl_hostboolean

Verifica el host.

Por defecto esfalse

Nota:

Esta opción está disponible tanto para envolturas del protocolo http como del ftp.

curl_verify_ssl_peerboolean

Requiere verificación del certificado SSL utilizado.

Por defecto esfalse

Nota:

Esta opción está disponible tanto para envolturas del protocolo http como del ftp.

Ejemplos

Ejemplo #1 Obtener una página y enviar datos POST

<?php

$postdata
=http_build_query(
array(
'var1'=>'some content',
'var2'=>'doh'
)
);

$opts= array('http'=>
array(
'method'=>'POST',
'header'=>'Content-type: application/x-www-form-urlencoded',
'content'=>$postdata
)
);

$context=stream_context_create($opts);

$result=file_get_contents('http://example.com/submit.php',false,$context);

?>



Opciones de contexto Phar

Opciones de contexto PharListado de opciones de contexto Phar

Descripción

Opciones de contexto paraphar://envoltura.

Opciones

comprimirint

Uno deConstantes de compresión Phar.

metadatamixed

Metadatos Phar. VerPhar::setMetadata().



Contexto parámetros

Contexto parámetrosListado de parámetros de contexto

Descripción

Estosparametrosse pueden establecer en uncontextousando el la funciónstream_context_set_params().

Parámetros

notificationcallable

Un valor de tipocallableque se llamará cuando se produce un evento en un flujo.

Véasestream_notification_callbackpara más detalles.



Opciones del contexto zip

Opciones del contexto zipListado de opciones del contexto zip

Descripción

Las opciones del contexto zip están disponibles para envolturaszip.

Opciones

password

Empleado para especificar la contraseña utilizada para el archivo encriptado.

Historial de cambios

VersiónDescripción
PHP 7.2.0, PECL zip 1.14.0Se añadiópassword.

Ejemplos

Ejemplo #1 Ejemplo de uso básicopassword

<?php
// Leer el fichero encriptado
$opciones= array(
'zip'=> array(
'password'=>'secret',
),
);
// Crear el contexto...
$contexto=stream_context_create($opciones);

// ...y emplearlo para recuperar los datos
echofile_get_contents('zip://test.zip#test.txt", false, $ctx);

?>


Tabla de contenidos



Protocolos y Envolturas soportados

PHP incorpora de serie envolturas para distintos protocolos tipo URL para trabajar junto con funciones del sistema de ficheros, comofopen(),copy(),file_exists()yfilesize(). Además de estas envolturas, se pueden definir por el usuario utilizando la funciónstream_wrapper_register().

Nota:La sintaxis de URL que se utiliza para describir una envoltura solo puede serscheme://.... Las sintaxisscheme:/yscheme:no están soportadas.


file://

file://Acceso al sistema de ficheros local

Descripción

ElSistema de Ficheroses la envoltura por omisión de PHP y representa al sistema de ficheros local. Cuando se proporciona una ruta relativa (esto es, no comienza con /, \, \\, ni con la letra de un dispositivo Windows) ésta se hará usando el directorio de trabajo actual. En muchos casos, se trata del directorio en el que se aloja el script, a no ser que se haya cambiado explicitamente. Si se utiliza la sapi CLI, apuntará al directorio desde el que se ejecutó el script.

En algunas funciones, como por ejemplofopen()ofile_get_contents(), puede usarse tambiéninclude_pathpara localizar ficheros con rutas relativas.

Uso

  • /ruta/al/fichero.ext
  • ruta/relativa/al/fichero.ext
  • ficheroEnDta.ext
  • C:/ruta/a/ficherowindows.ext
  • C:\ruta\a\ficherowindows.ext
  • \\servidorsmb\ruta\compartida\a\ficherowindows.ext
  • file:///ruta/al/fichero.ext

Opciones

Resumen de la Envoltura
AtributoPermitido
Restringido porallow_url_fopenNo
Permite Lecturas
Permite Escrituras
Permite Añadir contenidos
Permite Lecturas y Escrituras Simultáneas
Permite usar la funciónstat()
Permite usar la funciónunlink()
Permite usar la funciónrename()
Permite usar la funciónmkdir()
Permite usar la funciónrmdir()



http://

https://

http://--https://Acceso a URLS en HTTP(s)

Descripción

Permite acceso de lectura a ficheros/recursos mediante HTTP 1.0, utilizando el método GET de HTTP. Junto con la petición, se envía una cabeceraHost:para así poder usar hosts virtuales basados en nombres. Si se ha definido unuser_agenten el ficherophp.inio en el contexto del flujo, éste se incluirá también en la petición.

El flujo proporciona acceso alcuerpodel recurso; las cabeceras se guardan en la variable$http_response_header.

Si fuera importante conocer la URL del recurso del que procede el documento (tras procesar todas las redirecciones), se deberán procesar todas las cabeceras de respuesta devueltas por el flujo.

Se usará la directivafromen la cabeceraFrom:siempre que esté asignado y no se sobrescriba porOpciones y parámetros de contexto.

Uso

  • http://ejemplo.com
  • http://ejemplo.com/fichero.php?var1=val1&var2=val2
  • http://usuario:contraseña@ejemplo.com
  • https://ejemplo.com
  • https://ejemplo.com/fichero.php?var1=val1&var2=val2
  • https://usuario:contraseña@ejemplo.com

Opciones

Resumen de la Envoltura
AtributoPermitido
Restringido porallow_url_fopen
Permite Lecturas
Permite EscriturasNo
Permite Añadir contenidosNo
Permite Lecturas y Escrituras SimultáneasN/A
Permite usar la funciónstat()No
Permite usar la funciónunlink()No
Permite usar la funciónrename()No
Permite usar la funciónmkdir()No
Permite usar la funciónrmdir()No

Ejemplos

Ejemplo #1 Detectar la URL en la que se finaliza tras las redirecciones

<?php
$url
='http://www.example.com/redirecting_page.php';

$fp=fopen($url,'r');

$meta_data=stream_get_meta_data($fp);
foreach (
$meta_data['wrapper_data'] as$response) {

/* Were we redirected? */
if (strtolower(substr($response,0,10)) =='location: ') {

/* update $url with where we were redirected to */
$url=substr($response,10);
}

}

?>

Notas

Nota:Sólo habrá soporte para HTTPS cuando la extensiónopensslesté habilitada.

Las conexiones HTTP son de sólo lectura; no hay soporte para escribir o copiar datos a un recurso HTTP.

Se pueden enviar peticionesPOSTyPUT, por ejemplo, con ayuda de losContextos HTTP.

Ver también



ftp://

ftps://

ftp://--ftps://Acceso a URLs por FTP(s)

Descripción

Permite tanto lectura de ficheros existentes como la creación de nuevos ficheros vía FTP. La conexión fallará si el servidor no soporta FTP en modo pasivo.

Se puede tanto leer como escribir ficheros, pero no las dos cosas simultáneamente. Si el fichero remoto ya existiera en el servidor ftp, y se quisiera abrir en modo escritura sin especificar la opción de contextooverwrite, también fallará la conexión. Si fuera necesario sobrescribir un fichero ya existente en ftp, se tendrá que especificar la opción de contextooverwriteantes de abrir el fichero para su escritura. Alternativamente, puede usarse laextensión FTP.

Si se ha establecido la directivafromenphp.ini, se enviará como contraseña para conexiones de FTP anónimo.

Uso

  • ftp://ejemplo.com/pub/fichero.txt
  • ftp://usuario:contraseña@example.com/pub/fichero.txt
  • ftps://ejemplo.com/pub/fichero.txt
  • ftps://usuario:contraseña@ejemplo.com/pub/fichero.txt

Opciones

Resumen de la Envoltura
AtributosPermitido
Restringido porallow_url_fopen
Permite Lecturas
Permite EscriturasSí (ficheros nuevos. En los existentes conoverwrite)
Permite Añadir contenidos
Permite Lecturas y Escrituras SimultáneasNo
Permite usar la funciónstat()Sólo los elementosfilesize(),filetype(),file_exists(),is_file(), yis_dir(). Desde PHP 5.1.0:filemtime().
Permite usar la funciónunlink()
Permite usar la funciónrename()
Permite usar la funciónmkdir()
Permite usar la funciónrmdir()

Notas

Nota:

Hay soporte para FTPS desde PHP 4.3.0, siempre y cuando se haya compilado con soporte paraopenssl.

Si el servidor no soporta SSL, entonces la conexión se restablece a una conexión ftp regular sin encriptación.

Nota:Añadiendo contenido
Se puede añadir contenido a los ficheros mediante la envoltura de URLftp://.



php://

php://Acceso a distintos flujos de E/S

Descripción

PHP ofrece una serie de flujos de E/S generales que permiten acceder tanto a los flujos de entrada y salida de PHP, a la entrada estándar, a descriptores de ficheros de salida y de errores, a flujos de ficheros temporales en memoria y en disco, y a filtros para poder manipular otros recursos de ficheros según se lee desde o se escribe en ellos.

php://stdin, php://stdout y php://stderr

php://stdin,php://stdoutyphp://stderrpermiten acceder directamente al correspondiente flujo de entrada o salida del proceso de PHP. El flujo hace referencia a un descriptor de fichero duplicado, de modo que si se abrephp://stdiny más tarde se cierra, sólo se cerraría la copia del descriptor; el flujo real al que se refiereSTDINno se vería afectado. Tenga en cuenta que PHP mostraba un comportamiento irregular en este aspecto hasta PHP 5.2.1. Se recomienda utilizar simplemente las constantesSTDIN,STDOUTySTDERRen lugar de abrir flujos manualmente usando estas envolturas.

php://stdines de sólo lectura, mientras quephp://stdoutyphp://stderrson de sólo escritura.

php://input

php://inputes un flujo de sólo lectura que permite leer datos del cuerpo solicitado. En el caso de peticiones POST, es preferible usarphp://inputen vez de$HTTP_RAW_POST_DATAya que no depende de directivasphp.iniespeciales. Sin embargo, cuando no se genera automáticamente$HTTP_RAW_POST_DATA, se trata de una alternativa que hace un uso menos intensivo de memoria que activandoalways_populate_raw_post_data.php://inputno está disponible conenctype="multipart/form-data".

Nota:Antes de PHP 5.6, un flujo abierto conphp://inputsolamente podía leerse una vez; el flujo no admite operaciones de búsqueda. Sin embargo, dependiendo de la implementación de la SAPI, podría ser posible abrir otro flujophp://inputy reiniciar la lectura. Esto solamente es posible si los datos del cuerpo de la petición se han guardado. Este caso es típico en peticiones POST, pero no en otros métodos de petición, como PUT o PROPFIND.

php://output

php://outputes un flujo de sólo escritura que permite escribir en el buffer de salida tal como lo hacenprintyecho.

php://fd

php://fdpermite el acceso directo al descriptor de archivo dado. Por ejemplo,php://fd/3refiere al descriptor de archivo 3.

php://memory y php://temp

php://memoryyphp://tempson flujos de lectura-escritura que permiten almacenar datos temporales en una envoltura similar a un fichero. La única diferencia entre las dos es quephp://memorysiempre almacenará sus datos en memoria, mientras quephp://temputilizará un fichero temporal cuando la cantidad de datos almacenados superen el límite predefinido (por omisión, 2 MB). La ubicación de este fichero temporal está determinada de la misma manera que la funciónsys_get_temp_dir(),

El límite de memoria dephp://tempse puede controlar añadiendo/maxmemory:NN, dondeNNes la cantidad en bytes máxima de datos a almacenar en memoria antes de recurrir a un fichero temporal.

php://filter

php://filteres una especie de meta-envoltura diseñada para permitir aplicarfiltrosa los flujos en las aperturas. Esto es muy útil en las funciones todo en uno, comoreadfile(),file(), yfile_get_contents()donde, por otra parte, no se pueden aplicar filtros a los flujos antes de que se lea su contenido.

php://filteracepta los siguientes parámetros como parte de su ruta. Se pueden especifcar múltiples filtros en una ruta. Por favor, consulte los ejemplos para los usos concretors de estos parámetros.

parámetros de php://filter
NombreDescripción
resource=<flujo a filtrar>Este parámetro es obligatorio. Especifica el flujo que se desea filtrar.
read=<listra de filtros a aplicar a la cadena de lectura>Este parámetro es opcional. Se pueden enumerar uno o más filtros, separados por el carácter|.
write=<lista de filtros a aplicar a la cadena de escritura>Este parámetro es opcional. Se puedene enumerar uno o más filtros, separados por el carácter|.
<lista de filtros a aplicar a las dos cadenas>Cualquier listra de filtros que no esté precedida ni porread=ni porwrite=se aplicará tanto a las cadenas de lectura como de escritura según proceda.

Opciones

Resumen de la Envoltura (Paraphp://filter, consúltese el resumen de la envoltura que se filtra)
AtributoPermitido
Restringido porallow_url_fopenNo
Restringido porallow_url_includephp://input,php://stdin,php://memoryyphp://tempsolamente.
Permite Lecturasphp://stdin,php://input,php://fd,php://memoryyphp://tempsolamente.
Permite Escriturasphp://stdout,php://stderr,php://output,php://fd,php://memoryyphp://tempsolamente.
Permite Añadir contenidosphp://stdout,php://stderr,php://output,php://fd,php://memoryyphp://tempsolamente. (Equivalente a escrituras)
Permite Lecturas y Escrituras Simultáneasphp://fd,php://memoryyphp://tempsolamente.
Permite usar la funciónstat()php://memoryyphp://tempsolamente.
Permite usar la funciónunlink()No
Permite usar la funciónrename()No
Permite usar la funciónmkdir()No
Permite usar la funciónrmdir()No
Permite usar la funciónstream_select()php://stdin,php://stdout,php://stderr,php://fdyphp://tempsolamente.

Historial de cambios

VersiónDescripción
5.6.0php://inputse puede reutilzar.
5.3.6Se añadióphp://fd.
5.1.0Se añadieronphp://memoryyphp://temp.

Ejemplos

Ejemplo #1 php://temp/maxmemory

Este parámetro opcional permite establecer el límite de memoria a partir del cualphp://tempcomienza a usar un fichero temporal.

<?php
// Establecer el límite a 5 MB.
$fiveMBs=5*1024*1024;
$fp=fopen("php://temp/maxmemory:$fiveMBs",'r+');

fputs($fp,"hello\n");

// Leer lo que hemos escrito.
rewind($fp);
echo
stream_get_contents($fp);
?>

Ejemplo #2 php://filter/resource=<flujo a filtrar>

Este parámetro tiene que ubicarse al final de la especificación dephp://filtery tiene que apuntar al flujo que se desea filtrar.

<?php
/* Esto es equivalente a:
readfile("http://www.example.com");
dado que no se especifica ningún filtro */

readfile("php://filter/resource=http://www.example.com");
?>

Ejemplo #3 php://filter/read=<lista de filtros a aplicar a la cadena de lectura>

Este parámetro contiene uno o más nombres de filtros separados por el caracter|.

<?php
/* Devolverá el contenido de
www.example.com en mayúsculas */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");

/* Hará lo mismo que el ejemplo de arriba
pero además lo codificará en ROT13 */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>

Ejemplo #4 php://filter/write=<lista de filtros a aplicar a la cadena de escritura>

Este parámetro contiene uno o más nombres de filtros separados por el caracter|.

<?php
/* Filtrará el string "Hello World" con
el filtro rot13, y después lo escribirá en
example.txt dentro del directorio actual */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>

Ejemplo #5 php://memory y php://temp no son reutilizables

php://memoryyphp://tempno son reutilizabes, esto es, debepués de que los flujos hayan sido cerrados, no hay forma de hacer referencia a ellos de nuevo.

file_put_contents('php://memory', 'PHP');
echo file_get_contents('php://memory'); // no imprime nada


zlib://

bzip2://

zip://

zlib://--bzip2://--zip://Flujos de compresión

Descripción

zlib:PHP 4.0.4 - PHP 4.2.3 (sólo en sistemas con fopencookie)

compress.zlib://andcompress.bzip2://PHP 4.3.0 y superior

zlib:funciona comogzopen(), solo que usando el flujo, se puede utilizar confread()al igual que con otras funciones del sistema de ficheros. Esto quedó obsoleto en PHP 4.3.0 debido a la ambigüedad que surge con los nombres de fichero que contienen el caracter ':'; en su lugar, debe usarsecompress.zlib://.

compress.zlib://ycompress.bzip2://son equivalentes agzopen()y abzopen()respectivamente, y funcionan incluso en sistemas que no tienen soporte para fopencookie.

Laextensión ZIPregistra la envolturazip:.

Uso

  • compress.zlib://file.gz
  • compress.bzip2://file.bz2
  • zip://archive.zip#dir/file.txt

Opciones

Resumen de la Envoltura
AtributoPermitido
Restringido porallow_url_fopenNo
Permite Lecturas
Permite EscriturasSí (exceptozip://)
Permite Añadir contenidosSí (exceptozip://)
Permite Lecturas y Escrituras SimultaneasNo
Permite usar la funciónstat()No, utilice la envolturafile://para consultar la información de un fichero.
Permite usar la funciónunlink()No, utilice la envolturafile://para eliminar ficheros comprimidos.
Permite usar la funciónrename()No
Permite usar la funciónmkdir()No
Permite usar la funciónrmdir()No



data://

data://Data (RFC 2397)

Descripción

La envoltura del flujodata:(» RFC 2397) está disponible desde PHP 5.2.0.

Uso

  • data://text/plain;base64,

Opciones

Resumen de la envolutra
AtributoPermitido
Restringido porallow_url_fopenNo
Restringido porallow_url_include
Permite Lecturas
Permite EscriturasNo
Permite Añadir contenidoNo
Permite Lectura y Escritura SimultaneaNo
Permite usar la funciónstat()No
Permite usar la funciónunlink()No
Permite usar la funciónrename()No
Permite usar la funciónmkdir()No
Permite usar la funciónrmdir()No

Ejemplos

Ejemplo #1 Mostrar contenidos de data://

<?php
// muestra "I love PHP"
echofile_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
?>

Ejemplo #2 Obtener el Tipo de Medio

<?php
$fp
=fopen('data://text/plain;base64,','r');
$meta=stream_get_meta_data($fp);

// muestra "text/plain"
echo$meta['mediatype'];
?>


glob://

glob://Encuentra las rutas que coincidan con el patrón

Descripción

La envoltura del flujoglob:está disponible desde PHP 5.3.0.

Uso

  • glob://

Opciones

Resumen de la Envoltura
AtributoPermitido
Restringido porallow_url_fopenNo
Restringido porallow_url_includeNo
Permite LecturasNo
Permite EscriturasNo
Permite Añadir ContenidosNo
Permite Lecturas y Escrituras SimultáneasNo
Permite usar la funciónstat()No
Permite usar la funciónunlink()No
Permite usar la funciónrename()No
Permite usar la funciónmkdir()No
Permite usar la funciónrmdir()No

Ejemplos

Ejemplo #1 Uso básico

<?php
// Recorrer todos los ficheros *.php del directorio ext/spl/examples/
// y mostrar sus nombres y tamaños
$it= newDirectoryIterator("glob://ext/spl/examples/*.php");
foreach(
$itas$f) {
printf("%s: %.1FK\n",$f->getFilename(),$f->getSize()/1024);
}
?>
tree.php: 1.0K
findregex.php: 0.6K
findfile.php: 0.7K
dba_dump.php: 0.9K
nocvsdir.php: 1.1K
phar_from_dir.php: 1.0K
ini_groups.php: 0.9K
directorytree.php: 0.9K
dba_array.php: 1.1K
class_tree.php: 1.8K


phar://

phar://Archivo PHP

Descripción

La envoltura de flujophar://está disponible desde PHP 5.3.0. Para consultar una descripción detallada, reviseenvoltura del flujo Phar.

Uso

  • phar://

Opciones

Resumen de la Envoltura
AtributoPermitido
Restringido porallow_url_fopenNo
Restringido porallow_url_includeNo
Permite Lecturas
Permite Escrituras
Permite Añadir contenidosNo
Permite Lectura y Escritura Simultanea
Permite usar la funciónstat()
Permite usar la funciónunlink()
Permite usar la funciónrename()
Permite usar la funciónmkdir()
Permite usar la funciónrmdir()



ssh2://

ssh2://Secure Shell 2

Descripción

ssh2.shell://ssh2.exec://ssh2.tunnel://ssh2.sftp://ssh2.scp://(PECL)

Nota:Esta envoltura no está habilitada por omisión
Para poder usarse la envolturassh2.*://debe instalarase la extensión» SSH2disponible en» PECL.

Además de permitir hacer un login tradicional en la URI, la envoltura ssh2 también puede reutilizar las conexiones ya abiertas, proporcionando el recurso de conexión en el apartado host de la URL.

Uso

  • ssh2.shell://usuario:contraseña@ejemplo.com:22/xterm
  • ssh2.exec://usuario:contraseña@ejemplo.com:22/usr/local/bin/comando
  • ssh2.tunnel://usuario:contraseña@ejemplo.com:22/192.168.0.1:14
  • ssh2.sftp://usuario:contraseña@ejemplo.com:22/ruta/a/fichero

Opciones

Resumen de la Envoltura
Atributossh2.shellssh2.execssh2.tunnelssh2.sftpssh2.scp
Restringido porallow_url_fopen
Permite Lecturas
Permite EscriturasNo
Permite Añadir contenidosNoNoNoSí (cuando esté soportado por el servidor)No
Permite Lecturas y Escrituras SimultáneasNo
Permite usar la funciónstat()NoNoNoNo
Permite usar la funciónunlink()NoNoNoNo
Permite usar la funciónrename()NoNoNoNo
Permite usar la funciónmkdir()NoNoNoNo
Permite usar la funciónrmdir()NoNoNoNo

Opciones de contexto
NombreUsoValor por omisión
sessionRecurso ssh2 preconectado a utilizar 
sftpRecurso sftp preubicado a reutilizar 
methodsmétodos a usar de entre Key exchange, hostkey, cipher, compression, y MAC 
callbacks  
usernameNombre de usuario con el que conectar 
passwordContraseña a utilizar en autenticación con contraseña 
pubkey_fileNombre del fichero con la clave pública que se usará para autenticar 
privkey_fileNombre del fichero con la clave privada que se usará para autenticar 
envArray asociativo con las variables de entorno que se van a asignar 
termTipo de emulación del terminal a solicitar cuando se asigne un pty (pseudo terminal) 
term_widthAncho del terminal solicitado cuando se asigne un pty 
term_heightAltura del terminal solicitado cuando se asigne un pty 
term_unitsUnidades a usar con term_width y con term_heightSSH2_TERM_UNIT_CHARS

Ejemplos

Ejemplo #1 Abriendo un flujo a partir de una conexión activa

<?php
$session
=ssh2_connect('example.com',22);
ssh2_auth_pubkey_file($session,'username','/home/username/.ssh/id_rsa.pub',
'/home/username/.ssh/id_rsa','secret');
$stream=fopen("ssh2.tunnel://$session/remote.example.com:1234",'r');
?>

Ejemplo #2 ¡La variable$sessiondebe permanecer disponible!

Para utilizar la envolturassh2.*://$sessiondebe mantenerse el recurso$sessiondisponible. El código siguiente no tendrá el efecto deseado:

<?php
$session
=ssh2_connect('example.com',22);
ssh2_auth_pubkey_file($session,'username','/home/username/.ssh/id_rsa.pub',
'/home/username/.ssh/id_rsa','secret');
$connection_string="ssh2.sftp://$session/";
unset(
$session);
$stream=fopen($connection_string."path/to/file",'r');
?>

unset() cierra la sesión, ya que$connection_stringno contiene una referencia a la variable$session, simplemente una representación de la cadena derivada de ella. Esto también ocurre cuandounset()va implícito porque se sale del ámbito (como dentro de una función).



rar://

rar://RAR

Descripción

Esta envoltura se compone de una ruta al fichero RAR (relativa o absoluta) codificada como URL, un asterisco opcional (*), un signo de número opcional (#) y un nombre de entrada codificado como URL que también es opcional, tal como se almacena en el fichero. Cuando se especifique un nombre de entrada, será necesario también especificar un signo de número; además, se puede añadir al final del nombre una barra.

Esta envoltura puede abrir tanto ficheros como directorios. Cuando se abre un directorio, el signo asterisco obliga a que los nombres de las entradas del directorio se devuelvan decodificados. Si no se especifica, se devolverán codificadas como URL – esto es así para permitir hacer un uso correcto de la envoltura con determinadas funcionalidades, comoRecursiveDirectoryIteratorcuando se está en presencia de nombres de ficheros que podrían parecen datos codificados como URL.

Si no se proporciona ni un signo de número ni tampoco un número de entrada, se mostrará la raíz del fichero. La diferencia respecto a directorios convencionales es que el flujo no contendrá determinada información, tal como la fecha de modificación, dado que el directorio raíz no se almacena dentro el fichero comprimido en de una entrada individual. Para usar la envoltura conRecursiveDirectoryIteratores necesario que al acceder al raíz se incluya el signo de número en la URL, para que así las URLs de los nodos hijo se puedan construir correctamente.

Nota:Esta envoltura no está habilitada por omisión
Para poder usar la envolturarar://, debe instalarse la extensión» rardisponible en» PECL.

rar://Disponible desde PECL rar 3.0.0

Uso

  • rar://<nombre de archivo con codificación url>[*][#[<nombre de entrada con codificación url>]]

Opciones

Resumen de la Envoltura
AtributoPermitido
Restringido porallow_url_fopenNo
Restringido porallow_url_includeNo
Permite Lecturas
Permite EscriturasNo
Permite Añadir contenidoNo
Permite Lecturas y Escrituras SimultáneasNo
Permite usar la funciónstat()
Permite usar la funciónunlink()No
Permite usar la funciónrename()No
Permite usar la funciónmkdir()No
Permite usar la funciónrmdir()No

Opciones de contexto
NombreUsoValor por omisión
open_passwordSi la hubiera, contraseña utilizada para encriptar las cabeceras del archivo. WinRAR encriptará todos los ficheros con la misma contraseña que la cabecera siempre que ésta esté presente, por lo que se ignoraráfile_passworden archivos que contengan cabeceras encriptadas. 
file_passwordSi la hubiera, contraseña utilizada para encriptar un fichero. Si las cabeceras estuvieran también encriptadas, se ignoraría esta opción en favor deopen_password. El motivo por el que hay dos opciones es para así cubrir la posibilidad de que haya un archivo con contraseñas diferentes para la cabecera y los ficheros. Tenga en cuenta que si el archivo no tuviera sus cabeceras encriptadas, se ignoraríaopen_passwordy tendría que usarse en su lugar esta opción. 
volume_callbackLlamada de retorno que determina la ruta de las partes que no se hayan podido capturar. Para más información, reviseRarArchive::open(). 

Ejemplos

Ejemplo #1 Recorriendo un archivo RAR

<?php

classMyRecDirItextendsRecursiveDirectoryIterator{
function
current() {
return
rawurldecode($this->getSubPathName()) .
(
is_dir(parent::current())?" [DIR]":"");
}
}

$f="rar://".rawurlencode(dirname(__FILE__)) .
DIRECTORY_SEPARATOR.'dirs_and_extra_headers.rar#';

$it= newRecursiveTreeIterator(newMyRecDirIt($f));

foreach (
$itas$s) {
echo
$s,"\n";
}
?>

El resultado del ejemplo sería algo similar a:

|-allow_everyone_ni [DIR]
|-file1.txt
|-file2_אּ.txt
|-with_streams.txt
\-אּ [DIR]
  |-אּ\%2Fempty%2E [DIR]
  | \-אּ\%2Fempty%2E\file7.txt
  |-אּ\empty [DIR]
  |-אּ\file3.txt
  |-אּ\file4_אּ.txt
  \-אּ\אּ_2 [DIR]
    |-אּ\אּ_2\file5.txt
    \-אּ\אּ_2\file6_אּ.txt

Ejemplo #2 Abriendo un fichero encriptado (encriptación de cabeceras)

<?php
$stream
=fopen("rar://".
rawurlencode(dirname(__FILE__)) .DIRECTORY_SEPARATOR.
'encrypted_headers.rar'.'#encfile1.txt',"r",false,
stream_context_create(
array(
'rar'=>
array(
'open_password'=>'samplepassword'
)
)
)
);
var_dump(stream_get_contents($stream));
/* ni la fecha de creación ni la de último acceso es obligatoria WinRAR,
* por esa razón la mayoría de ficheros no lo tendrán */
var_dump(fstat($stream));
?>

El resultado del ejemplo sería algo similar a:

string(34) "Contenido del fichero encriptado 1"
Array
(
    [0] => 0
    [1] => 0
    [2] => 33206
    [3] => 1
    [4] => 0
    [5] => 0
    [6] => 0
    [7] => 26
    [8] => 0
    [9] => 1259550052
    [10] => 0
    [11] => -1
    [12] => -1
    [dev] => 0
    [ino] => 0
    [mode] => 33206
    [nlink] => 1
    [uid] => 0
    [gid] => 0
    [rdev] => 0
    [size] => 26
    [atime] => 0
    [mtime] => 1259550052
    [ctime] => 0
    [blksize] => -1
    [blocks] => -1
)


ogg://

ogg://Flujos de audio

Descripción

Los ficheros que se abran para lectura usando la envolturaogg://se utilizan como codificaciones de audio comprimido usando el códecOGG/Vorbis. De forma similar, los ficheros abiertos para escritura o para añadir contenido usando la envolturaogg://se escriben como datos de audio comprimidos. Cuando se use la funciónstream_get_meta_data()con un ficheroOGG/Vorbisabierto para lectura, se devolverán diversos detalles del flujo, incluyendo la etiquetavendor, cualquiercommentsque se haya añadido, el número de canaleschannels, elratiode muestreo, y el rango del ratio de codificación descrito por:bitrate_lower,bitrate_upper,bitrate_nominal, ybitrate_window.

ogg://(PECL)

Nota:Esta envoltura no está habilitada por omisión
Para usar la envolturaogg://es necesario instalar la extensión» OGG/Vorbisdisponible en» PECL.

Uso

  • ogg://soundfile.ogg
  • ogg:///path/to/soundfile.ogg
  • ogg://http://www.example.com/path/to/soundstream.ogg

Opciones

Resumen de la Envoltura
AtributoPermitido
Restringido porallow_url_fopenNo
Permite Lecturas
Permite Escrituras
Permite Añadir contenido
Permite Lecturas y Escrituras SimultáneaNo
Permite usar la funciónstat()No
Permite usar la funciónunlink()No
Permite usar la funciónrename()No
Permite usar la funciónmkdir()No
Permite usar la funciónrmdir()No

Opciones de contexto
NombreUsoValor por omisiónModo
pcm_modecodificación PCM que se aplicará en las lecturas, de entre:OGGVORBIS_PCM_U8,OGGVORBIS_PCM_S8,OGGVORBIS_PCM_U16_BE,OGGVORBIS_PCM_S16_BE,OGGVORBIS_PCM_U16_LE, yOGGVORBIS_PCM_S16_LE. (8 o 16 bit, con o sin signo, big o littleendian)OGGVORBIS_PCM_S16_LELectura
rateRatio de muestreo en datos de entradas, expresado en Hz44100Escritura/Adición
bitrateSi es un entero, definirá el bitrate fijo al que se codificará. (de 16000 a 131072) Si es un real, definirá la calidad del bitrate variable a usar. (de -1.0 a 1.0)128000Escritura/Adición
channelsEl número de canales de audio a codificar, normalmente 1 (mono), o 2 (estéreo). Puede llegar a 16.2Escritura/Adición
commentsUn array de strings a codificar en la cabecera de la pista. Escritura/Adición

Ejemplos



expect://

expect://Flujos de Interacción de Procesos

Descripción

Los flujos que se hayan abierto con la envolturaexpect://, darán acceso a stdio, stdout y stderr (entrada, salida y errores estándar respectivamente) de los procesos, vía PTY.

Nota:Esta envoltura no está habilitada por omisión
Para poder usar la envolturaexpect://se debe instalar la extensión» Expectdisponible en» PECL.

expect://(PECL)

Uso

  • expect://command

Opciones

Resumen de la Envoltura
AtributoPermitido
Restringido porallow_url_fopenNo
Permites Lecturas
Permite EscriturasNo
Permite Añadir contenido
Permite Lecturas y Escrituras SimultáneasNo
Permite usar la funciónstat()No
Permite usar la funciónunlink()No
Permite usar la funciónrename()No
Permite usar la funciónmkdir()No
Permite usar la funciónrmdir()No

Ejemplos


Tabla de contenidos




Seguridad


Introducción

PHP es un potente lenguaje, y su intérprete, bien como módulo del servidor web o bien como binarioCGI, puede acceder a ficheros, ejecutar comandos o abrir conexiones de red desde el servidor. Estas propiedades hacen que, por omisión, sea inseguro todo lo que se ejecute en un servidor web. PHP está diseñado específicamente para ser un lenguaje más seguro para escribir aplicacionesCGIque Perl o C. Partiendo de un correcto ajuste de opciones de configuración para tiempo de ejecución y en tiempo de compilación, y el uso de prácticas de programación apropiadas, pueden proporcionarle la combinación de libertad y de seguridad que necesita.

Dado que hay muchas vías para ejecutar PHP, existen muchas opciones de configuración para controlar su comportamiento. Al haber una extensa selección de opciones se garantiza poder usar PHP para un gran número de propósitos, pero a la vez significa que existen combinaciones que conllevan una configuración menos segura.

La flexibilidad de configuración de PHP rivaliza igualmente con la flexibilidad de su código. PHP puede ser usado para construir completas aplicaciones de servidor, con toda la potencia de un usuario de consola, o se puede usar sólo desde el lado del servidor implicando un menor riesgo dentro de un entorno controlado. El cómo construir ese entorno, y cómo de seguro es, depende del desarrollador PHP.

Este capítulo comienza con algunos consejos generales de seguridad, explica las diferentes combinaciones de opciones de configuración y las situaciones en que pueden ser útiles, y describe diferentes consideraciones relacionadas con la programación de acuerdo a diferentes niveles de seguridad.



Consideraciones generales

Un sistema completamente seguro es prácticamente un imposible, de modo que el enfoque usado con mayor frecuencia en la profesión de seguridad es uno que busque el balance adecuado entre riesgo y funcionalidad. Si cada variable enviada por un usuario requiriera de dos formas de validación biométrica (como rastreo de retinas y análisis dactilar), usted contaría con un nivel extremadamente alto de confiabilidad. También implicaría que llenar los datos de un formulario razonablemente complejo podría tomar media hora, cosa que podría incentivar a los usuarios a buscar métodos para esquivar los mecanismos de seguridad.

La mejor seguridad con frecuencia es lo suficientemente razonable como para suplir los requerimientos dados sin prevenir que el usuario realice su labor de forma natural, y sin sobrecargar al autor del código con una complejidad excesiva. De hecho, algunos ataques de seguridad son simples recursos que aprovechan las vulnerabilidades de este tipo de seguridad sobrecargada, que tiende a erosionarse con el tiempo.

Una frase que vale la pena recordar: Un sistema es apenas tan bueno como el eslabón más débil de una cadena. Si todas las transacciones son registradas copiosamente basándose en la fecha/hora, ubicación, tipo de transacción, etc. pero la verificación del usuario se realiza únicamente mediante una cookie sencilla, la validez de atar a los usuarios al registro de transacciones es mermada severamente.

Cuando realice pruebas, tenga en mente que no será capaz de probar todas las diferentes posibilidades, incluso para las páginas más simples. Los datos de entrada que usted puede esperar en sus aplicaciones no necesariamente tendrán relación alguna con el tipo de información que podría ingresar un empleado disgustado, un cracker con meses de tiempo entre sus manos, o un gato doméstico caminando sobre el teclado. Es por esto que es mejor observar el código desde una perspectiva lógica, para determinar en dónde podrían introducirse datos inesperados, y luego hacer un seguimiento de cómo esta información es modificada, reducida o amplificada.

Internet está repleto de personas que tratan de crearse fama al romper la seguridad de su código, bloquear su sitio, publicar contenido inapropiado, y por lo demás haciendo que sus días sean más interesantes. No importa si usted administra un sitio pequeño o grande, usted es un objetivo por el simple hecho de estar en línea, por tener un servidor al cual es posible conectarse. Muchas aplicaciones de cracking no hacen distinciones por tamaños, simplemente recorren bloques masivos de direcciones IP en busca de víctimas. Trate de no convertirse en una.



Instalado como CGI binario

Tabla de contenidos


Ataques posibles

Usar PHP como un binarioCGIes una opción para configuraciones que por alguna razón no desean integrar PHP como un módulo dentro del software de servidor (como Apache), o usarán PHP con diferentes tipos de envoltoriosCGIpara crear entornos seguros chroot y setuid para scripts. Esta configuración usualmente involucra la instalación del binario ejecutable de PHP en el directorio cgi-bin del servidor web. La recomendación» CA-96.11del CERT recomienda que está en contra de colocar cualquiera de los intérpretes dentro de cgi-bin. Aún si el binario de PHP puede ser usado como un intérprete independiente, PHP está diseñado para prevenir los ataques que esta configuración hace posible:

  • Accediendo a los ficheros del sistema:http://mi.servidor/cgi-bin/php?/etc/passwdLa consulta de información en una URL después del signo de interrogación (?) es pasado como argumento de la línea de comandos al intérprete por la interfaz del CGI. Usualmente los intérpretes abren y ejecutan el fichero especificado como el primer argumento en la línea de comandos.Cuando es invocado como un binario de CGI, PHP se rehusa a interpretar los argumentos de línea de comandos.
  • Accediendo a cualquier documento web en el servidor:http://mi.servidor/cgi-bin/php/directorio/secreto/doc.htmlParte de la ruta de información de la URL después del nombre del binario de PHP,/directorio/secreto/doc.htmles convencionalmente utilizado para especificar el nombre del fichero a ser abierto e interpretado por el programaCGI. Usualmente las directivas de configuración de algunos servidores web (Apache: Acción) son utilizados para redirigir peticiones a los documentos comohttp://mi.servidor/directorio/secreto/script.phpal intérprete de PHP. Con esta configuración, el servidor web revisa primero los permisos de acceso a los directorios/directorio/secreto, y después crea la petición redirigidahttp://mi.servidor/cgi-bin/php/directorio/secreto/script.php. Desafortunadamente, si la petición es proporcionada originalmente en esta forma, no se revisan los accesos a los directorios hechos por el servidor web/directorio/secreto/script.php, sino solamente al fichero/cgi-bin/php. De esta forma/cgi-bin/phpcualquier usuario está habilitado a acceder a cualquier documento protegido en el servidor web.En PHP, las directivas de configuración en tiempo de ejecucióncgi.force_redirect,doc_rootyuser_dirpueden ser utilizadas para prevenir este ataque, si el árbol de documentos del servidor tiene cualquiera de estos directorios con restricciones de acceso. Véase más abajo para una explicación completa de las diferentes combinaciones.


Caso 1: Ficheros públicos servidos solamente

Si su servidor no tiene ningún contenido que no esté restringido por contraseña o control de acceso basado en IP, no hay necesidad de estas opciones de configuración. Si su servidor web no le permite hacer redirecciones, o el servidor no tiene una forma de comunicar al binario de PHP que la petición es una forma segura de petición de redireccionamiento, puede especificar la opción--enable-force-cgi-redirectpara el script de configuración. Usted todavía tiene que asegurarse que sus scripts de PHP no confían en una forma o en otra para llamar el script, ni directamentehttp://my.host/cgi-bin/php/dir/script.phpni por redirecciónhttp://my.host/dir/script.php.

La redirección puede ser configurada en Apache utilizando directivas Action y AddHandler (vea más abajo).



Caso 2: utilizandocgi.force_redirect

La directiva de configuracióncgi.force_redirectpreviene a cualquiera que llame a PHP directamente por medio de una URL como estahttp://mi.servidor/cgi-bin/php/directoriosecreto/script.php. En cambio, PHP solamente lo analizará en este modo si éste se ha ido a través de una regla directa del servidor web.

Usualmente la redirección en la configuración de Apache se hace con las siguientes directivas:

Action php-script /cgi-bin/php
AddHandler php-script .php

Esta opción ha sido probada solamente con el servidor web Apache, y se basa en que en Apache se configure en una variable de entorno no-estándar de CGIREDIRECT_STATUSpara peticiones de redirección. Si su servidor web no soporta ninguna forma de decirle si la petición es directa o redirigida, usted no puede utilizar esta opción y debe usar una de las otras formas de ejecutar la versión CGI aquí documentadas.



Caso 3: Configurando doc_root o user_dir

Para incluir contenido activo, como scripts y ejecutables, en los directorios de documentos del servidor web es algunas veces considerado una práctica insegura. Si, por el hecho del algún error de configuración, los scripts no se ejecutan y son mostrados como documentos HTML regulares, esto podría resultar en una fuga de información de propiedad intelectual o de información de seguridad como las contraseñas. Por lo tanto muchos Administradores de Sistemas preferirán configurar otra estructura de directorios para scripts que sean accesibles solamente a través del CGI de PHP, y por lo tanto siempre interpretado y no desplegado como tal.

También si el método para asegurar las peticiones no es redirigido, como se describió en la sección anterior, no está disponible, es necesario configurar un script doc_root que sea diferente de la raíz del documento web.

Usted puede configurar el script de la raíz de documento de PHP en la directiva de configuracióndoc_rooten elfichero de configuración, o puede configurar la variable de entornoPHP_DOCUMENT_ROOT. Si éste es configurado, la versión delCGIde PHP siempre construirá el nombre del fichero para abrir con estedoc_rooty la ruta de información en la petición, de tal forma que pueda estar seguro que ningún script será ejecutado fuera de este directorio (excepto poruser_dirque se encuentra más abajo).

Otra opción utilizable es estauser_dir. Cuando user_dir no está configurado, lo único que controla el fichero abierto esdoc_root. Al abrir una URL comohttp://mi.servidor/~usuario/documento.phpno resulta en la apertura de un fichero bajo el directorio personal de los usuarios, pero si un fichero llamado~usuario/documento.phpdebajo de doc_root (si, un nombre de directorio que inicia con una a tilde [~]).

Si user_dir es configurado, por ejemplopublic_php, una petición comohttp://mi.servidor/~usuario/doc.phpabrirá un fichero llamadodoc.phpbajo el directorio llamadopublic_phpdebajo de el directorio personal del usuario. Si el directorio personal del usuario es/home/usuario, el fichero ejecutado será/home/user/public_php/doc.php.

La expansión deuser_dirsucede sin tomar en cuenta la configuración dedoc_root, así que usted puede controlar el acceso a la raíz de los documentos y el directorio de los usuarios separadamente.



Caso 4: El analizador de PHP fuera del árbol de la web

Una opción muy segura es poner el binario analizador de PHP en algún lugar fuera del árbol de ficheros de la web. En/usr/local/bin, por ejemplo. El único inconveniente real con esta opción es que ahora tendrá que poner una línea similar a:

#!/usr/local/bin/php
como la primera línea de cualquier fichero que contenga etiquetas de PHP. También necesitará hacer que el fichero sea ejecutable. Eso significa, tratarlo exactamente como trataría cualquier otro script de CGI escrito en Perl, sh, bash, o cualquier otro lenguaje común de script el cual utilice#!como mecanismo de ejecución de si mismo.

Para que PHP maneje la información correctamente dePATH_INFOyPATH_TRANSLATEDcon esta configuración, el analizador de PHP debería ser compilado con la opción de configuración--enable-discard-path.




Instalado como módulo de Apache

CuandoPHPes usado como un módulo de Apache, hereda los permisos del usuario de Apache (generalmente los del usuario "nobody"). Este hecho representa varios impactos sobre la seguridad y las autorizaciones. Por ejemplo, si se está usandoPHPpara acceder a una base de datos, a menos que tal base de datos disponga de un control de acceso propio, se tendrá que hacer que la base de datos sea asequible por el usuario "nobody". Esto quiere decir que un script malicioso podría tener acceso y modificar la base de datos, incluso sin un nombre de usuario y contraseña. Es completamente posible que una araña web (bot) pudiera toparse con la página web de administración de una base de datos, y eliminar todo de la base de datos. Una protección ante este tipo de situaciones es mediante el uso del mecanismo de autorización de Apache, o con modelos de acceso de diseño propio usando LDAP, archivos.htaccess, etc. e incluir ese código como parte de los scriptsPHP.

Con frecuencia, una vez la seguridad se ha establecido en un punto en donde el usuario dePHP(en este caso, el usuario de apache) tiene asociada muy poco riesgo, se descubre quePHPse encuentra ahora imposibilitado de escribir archivos en los directorios de los usuarios. O quizás se le haya desprovisto de la capacidad de acceder o modificar bases de datos. Se ha prevenido que pudiera escribir tanto archivos buenos como malos, o que pudiera realizar transacciones buenas o malas en la base de datos.

Un error de seguridad cometido con frecuencia en este punto es darle permisos de administrador (root) a apache, o incrementar las habilidades del usuario de apache de alguna otra forma.

Incrementar los permisos del usuario de Apache hasta el nivel de administrador es extremadamente peligroso y puede comprometer al sistema entero, así que el uso de entornos sudo, chroot, o cualquier otro mecanismo que sea ejecutado como root no debería ser considerado como una opción por aquellos que no son profesionales en seguridad.

Existen otras soluciones más simples. Mediante el uso deopen_basedirse puede controlar y restringir qué directorios pueden ser usados porPHP. También se pueden definir áreas solo-Apache, para restringir todas las actividades basadas en web a archivos que no son de usuarios o del sistema.



Seguridad de una Sesión

Es importante mantener seguro el manejo de sesión HTTP. La seguridad relacionada a la Sesión está descrita enSeguridad de Sesiónen la sección de referenciaMódulo de Sesión.



Seguridad del Sistema de Archivos

Tabla de contenidos

PHPestá sujeto a la seguridad integrada en la mayoría de sistemas de servidores con respecto a los permisos de archivos y directorios. Esto permite controlar qué archivos en el sistema de archivos se pueden leer. Se debe tener cuidado con los archivos que son legibles para garantizar que son seguros para la lectura por todos los usuarios que tienen acceso al sistema de archivos.

Desde quePHPfue diseñado para permitir el acceso a nivel de usuarios para el sistema de archivos, es perfectamente posible escribir un scriptPHPque le permita leer archivos del sistema como /etc/passwd, modificar sus conexiones de red, enviar trabajos de impresión masiva, etc. Esto tiene algunas implicaciones obvias, es necesario asegurarse que los archivos que se van a leer o escribir son los apropiados.

Considere el siguiente script, donde un usuario indica que quiere borrar un archivo en su directorio home. Esto supone una situación en la que una interfaz web enPHPes usada regularmente para gestionar archivos, por lo que es necesario que el usuario Apache pueda borrar archivos en los directorios home de los usuarios.

Ejemplo #1 Un control pobre puede llevar a ....

<?php
// eliminar un archivo del directorio personal del usuario
$username=$_POST['user_submitted_name'];
$userfile=$_POST['user_submitted_filename'];
$homedir="/home/$username";

unlink("$homedir/$userfile");

echo
"El archivo ha sido eliminado!";
?>
Dado que el nombre de usuario y el nombre del archivo son enviados desde un formulario, estos pueden representar un nombre de archivo y un nombre de usuario que pertenecen a otra persona, incluso se podría borrar el archivo a pesar que se supone que no estaría permitido hacerlo. En este caso, usted desearía usar algún otro tipo de autenticación. Considere lo que podría suceder si las variables enviadas son "../etc/" y "passwd". El código entonces se ejecutaría efectivamente como:

Ejemplo #2 ... Un ataque al sistema de archivos

<?php
// elimina un archivo desde cualquier lugar en el disco duro al que
// el usuario de PHP tiene acceso. Si PHP tiene acceso de root:
$username=$_POST['user_submitted_name'];// "../etc"
$userfile=$_POST['user_submitted_filename'];// "passwd"
$homedir="/home/$username";// "/home/../etc"

unlink("$homedir/$userfile");// "/home/../etc/passwd"

echo"El archivo ha sido eliminado!";
?>
Hay dos medidas importantes que usted debe tomar para prevenir estas cuestiones.
  • Únicamente permisos limitados al usuario web dePHP.
  • Revise todas las variables que se envían.
Aquí está una versión mejorada del script:

Ejemplo #3 Comprobación más segura del nombre de archivo

<?php
// elimina un archivo del disco duro al que
// el usuario de PHP tiene acceso.
$username=$_SERVER['REMOTE_USER'];// usando un mecanismo de autenticación
$userfile=basename($_POST['user_submitted_filename']);
$homedir="/home/$username";

$filepath="$homedir/$userfile";

if (
file_exists($filepath) &&unlink($filepath)) {
$logstring="Se ha eliminado$filepath\n";
} else {
$logstring="No se ha podido eliminar$filepath\n";
}
$fp=fopen("/home/logging/filedelete.log","a");
fwrite($fp,$logstring);
fclose($fp);

echo
htmlentities($logstring,ENT_QUOTES);

?>
Sin embargo, incluso esto no está exento de defectos. Si la autenticación del sistema permite a los usuarios crear sus propios inicios de sesión de usuario, y un usuario eligió la entrada "../etc/", el sistema está expuesto una vez más. Por esta razón, puede que prefiera escribir un chequeo más personalizado:

Ejemplo #4 Comprobación más segura del nombre de archivo

<?php
$username
=$_SERVER['REMOTE_USER'];// usando un mecanismo de autenticación
$userfile=$_POST['user_submitted_filename'];
$homedir="/home/$username";

$filepath="$homedir/$userfile";

if (!
ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD',$userfile)) {
die(
"nombre de usuario o nombre de archivo incorrecto");
}

//etc...
?>

Dependiendo de sus sistema operativo, hay una gran variedad de archivos a los que debe estar atento, esto incluye las entradas de dispositivos (/dev/ o COM1), archivos de configuracion (archivos /etc/ y archivos .ini), las muy conocidas carpetas de almacenamiento (/home/, Mis documentos), etc. Por esta razón, por lo general es más fácil crear una política en donde se prohíba todo excepto lo que expresamente se permite.


Cuestiones relacionadas a bytes nulos

ComoPHPutiliza las funciones de C para operaciones relacionadas al sistema de archivos, se podría manejar bytes nulos de manera bastante inesperada. Como un byte nulo denota el fin de una cadena en C, las cadenas que contengan estos no serán consideradas por completo, sino sólo hasta que ocurra un byte nulo. El siguiente ejemplo muestra un código vulnerable que presenta este problema:

Ejemplo #1 Script vulnerable a bytes nulos

<?php
$file
=$_GET['file'];// "../../etc/passwd\0"
if (file_exists('/home/wwwrun/'.$file.'.php')) {
// file_exists devolverá true si el archivo /home/wwwrun/../../etc/passwd existe
include'/home/wwwrun/'.$file.'.php';
// el archivo /etc/passwd se incluirá
}
?>

Por lo tanto, cualquier cadena que se utiliza en una operación de sistema de archivos siembre deben ser validados correctamente. He aquí una versión mejorada del ejemplo anterior:

Ejemplo #2 Validando correctamente la entrada

<?php
$file
=$_GET['file'];

// Lista blanca de valores posibles
switch ($file) {
case
'main':
case
'foo':
case
'bar':
include
'/home/wwwrun/include/'.$file.'.php';
break;
default:
include
'/home/wwwrun/include/main.php';
}
?>



Seguridad en bases de datos

Tabla de contenidos

Hoy en día, las bases de datos son componentes esenciales de cualquier aplicación web, permitiendo a los sitios web proveer variedad de contenido dinámico. Puesto que se puede almacenar información muy delicada o secreta en una base de datos, debería considerarse ampliamente proteger las bases de datos.

Para obtener o almacenar cualquier información, es necesario conectarse a la base de datos, enviar una consulta válida, obtener el resultado, y cerrar la conexión. Hoy en día, el lenguaje de consultas más utilizado en esta interacción es el Lenguaje Estructurado de Consultas (SQL, por sus siglas en inglés). Vea como un atacante puederealizar manipulaciones maliciosas con una consulta SQL.

Como es de suponer,PHPno puede proteger una base de datos por sí mismo. Las siguientes secciones tienen como objetivo ser una introducción básica de cómo acceder y manipular bases de datos dentro de scripts dePHP.

Tenga en mente esta sencilla regla: Protección en profundidad. En cuantos más sitios se tomen acciones para aumentar la protección de una base de datos, menor es la probabilidad de que un atacante tenga éxito en exponer o abusar de cualquier información que tenga almacenada. Un buen diseño del esquema de la base de datos y de la aplicación se ocupará de sus mayores temores.


Diseño de bases de datos

El primer paso es siempre crear una base de datos, a menos que se quiera utilizar una de un tercero. Cuando se crea una base de datos, esta es asignada a un propietario, aquel que ejecutó la sentencia de creación. Usualmente, sólo el propietario (o un superusuario) puede hacer cualquier cosa con los objetos de esa base de datos. Para que otros usuarios puedan utilizarla, se les deben conceder privilegios.

Las aplicaciones nunca deberían conectarse a la base de datos como su propietario o como un superusuario, porque estos usuarios pueden ejecutar cualquier consulta a su antojo; por ejemplo, modificar el esquema (p.ej., eliminar tablas) o borrar su contenido por completo.

Se pueden crear distintos usuarios de una base de datos para cada aspecto de la aplicación con permisos muy limitados a los objetos de dicha base de datos. Solamente deberían otorgarse los privilegios necesarios, evitando así que el mismo usuario pueda interactuar con la base de datos en diferentes casos y uso. Esto significa que si un intruso obtiene acceso a una base de datos utilizando las credenciales de la aplicación, solamente puede efectuar los cambios que la aplicación permita.



Conexión a una base de datos

Se pueden establecer las conexiones sobre SSL para cifrar las comunicaciones cliente/servidor y aumentar la seguridad, o también emplear ssh para cifrar la conexión de red entre los clientes y el servidor de bases de datos. Si se utiliza algunas de estas opciones, será difícil para un posible atacante la monitorización del tráfico y la obtención de información de la base de datos.



Modelo de almacenamiento cifrado

SSL/SSH protege los datos que viajan desde el cliente al servidor: SSL/SSH no protege los datos persistentes almacenados en una base de datos. SSL es un protocolo que protege los datos mientras viajan por el cable.

Una vez que un atacante obtiene acceso directo a una base de datos (eludiendo el servidor web), los datos sensibles almacenados podrían ser divulgados o mal utilizados, a menos que la información esté protegida por la base de datos misma. Cifrar los datos es una buena forma de mitigar esta amenaza, pero muy pocas bases de datos ofrecen este tipo de cifrado de datos.

La forma más sencilla para evitar este problema es crear primero un paquete de cifrado propio y utilizarlo en los scripts dePHP. Hay muchas extensiones dePHPque pueden ser de ayuda para esto, tales comoMcryptyMhash, cubriendo así una amplia variedad de algoritmos de cifrado. El script cifra los datos antes de insertarlos en la base de datos, y los descifra al obtenerlos. Véanse las referencias para ejemplos adicionales del funcionamiento del cifrado.

'Hashing'

En caso de datos que deban estar realmente ocultos, si no fuera necesaria su representación real, (es decir, que no sean mostrados), quizás convenga utilizar algoritmos hash. El ejemplo más típico del uso del hash es a la hora de almacenar el hash criptográfico de una contraseña en una base de datos, en lugar de almacenar la contraseña en sí.

En PHP 5.5 o posterior las funciones depasswordproporcionan una forma adecuada de utilizar hash con datos delicados y trabajar con estos hash. En PHP 5.3.7+ se puede utilizar también la biblioteca» password_compat.

password_hash()se emplea para usar un hash con una cadena dada utilizando el algoritmo más fuerte actualmente disponible, mientras quepassword_verify()comprueba si la contraseña dada coincide con el hash almacenado en la base de datos.

Ejemplo #1 Campo de contraseña con hash

<?php

// Almacenar el hash de la contraseña
$consulta=sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
pg_escape_string($nombre_usuario),
password_hash($contraseña,PASSWORD_DEFAULT));
$resultado=pg_query($conexión,$consulta);

// Consultar si el usuario envió la contraseña correcta
$consulta=sprintf("SELECT pwd FROM users WHERE name='%s';",
pg_escape_string($nombre_usuario));
$fila=pg_fetch_assoc(pg_query($conexión,$consulta));

if (
$fila&&password_verify($contraseña,$fila['pwd'])) {
echo
'Bienvenido, '.htmlspecialchars($nombre_usuario) .'!';
} else {
echo
'La autenticación ha fallado para '.htmlspecialchars($nombre_usuario) .'.';
}

?>

En versiones anteriores de PHP esto se puede realizar con la funcióncrypt().

Ejemplo #2 Contraseña con hash utilizandocrypt()

<?php


// Almacenar el hash de la contraseña
// $caracteres_aleatorios se obtuvo, p.ej., utilizando /dev/random
$consulta=sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
pg_escape_string($nombre_usuario),
pg_escape_string(crypt($contraseña,'$2a$07$'.$caracteres_aleatorios.'$')));
$resultado=pg_query($conexión,$consulta);

// Consultar si el usuario envió la contraseña correcta
$consulta=sprintf("SELECT pwd FROM users WHERE name='%s';",
pg_escape_string($nombre_usuario));
$fila=pg_fetch_assoc(pg_query($conexión,$consulta));

if (
$fila&&crypt($contraseña,$fila['pwd']) ==$fila['pwd']) {
echo
'Bienvenido, '.htmlspecialchars($nombre_usuario) .'!';
} else {
echo
'La autenticación ha fallado para '.htmlspecialchars($nombre_usuario) .'.';
}

?>


Inyección de SQL

Muchos desarrolladores web no son conscientes de cómo las consultas SQL pueden ser manipuladas, y asumen que una consulta SQL es una orden fiable. Esto significa que las consultas SQL son capaces de eludir controles de acceso, evitando así las comprobaciones de autenticación y autorización estándar, e incluso algunas veces, que las consultas SQL podrían permitir el acceso a comandos al nivel del sistema operativo del equipo anfitrión.

La inyección directa de comandos SQL es una técnica donde un atacante crea o altera comandos SQL existentes para exponer datos ocultos, sobrescribir los valiosos, o peor aún, ejecutar comandos peligrosos a nivel de sistema en el equipo que hospeda la base de datos. Esto se logra a través de la práctica de tomar la entrada del usuario y combinarla con parámetros estáticos para elaborar una consulta SQL. Los siguientes ejemplos están basados en historias reales, desafortunadamente.

Debido a la falta de validación en la entrada de datos y a la conexión a la base de datos con privilegios de superusuario o de alguien con privilegios para crear usuarios, el atacante podría crear un superusuario en la base de datos.

Ejemplo #1 Dividir el conjunto de resultados en páginas ... y crear superusuarios (PostgreSQL)

<?php

$índice
=$argv[0];// ¡Cuidado, no hay validación en la entrada de datos!
$consulta="SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET$índice;";
$resultado=pg_query($conexión,$consulta);

?>
Un usuario común hace clic en los enlaces 'siguiente' o 'atrás' donde el$índiceestá codificado en elURL. El script espera que el$índiceentrante sea un número décimal. Sin embargo, ¿qué pasa si alguien intenta irrumpir anteponiendo a laURLalgo como lo siguiente empleandourlencode()?
0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
    select 'crack', usesysid, 't','t','crack'
    from pg_shadow where usename='postgres';
--
Si esto sucediera, el script podría otrogar un acceso de superusuario al atacante. Observe que0;es para proveer un índcie válido a la consulta original y así finalizarla.

Nota:

Es una técnica común forzar al analizador de SQL a ignorar el resto de la consulta escrita por el desarrollador con--, lo cual representa un comentario en SQL.

Una forma factible de obtener contraseñas es burlar las páginas de búsqueda de resultados. Lo único que el atacante necesita hacer es ver si hay variables que hayan sido enviadas y sean empleadas en sentencias SQL que no sean manejadas apropiadamente. Estos filtros se pueden establecer comunmente en un formulario anterior para personalizar las cláusulasWHERE, ORDER BY, LIMITyOFFSETen las sentenciasSELECT. Si la base de datos admite el constructorUNION, el atacante podría intentar anteponer una consulta entera a la consulta original para enumerar las contraseñas de una tabla arbitraria. Se recomienda encarecidamente utilizar campos de contraseña encriptadas.

Ejemplo #2 Enumerar artículos ... y algunas contraseñas (cualquier servidor de bases de datos)

<?php

$consulta
="SELECT id, name, inserted, size FROM products
WHERE size = '
$tamaño'";
$resultado=odbc_exec($conexión,$consulta);

?>
La parte estática de la consulta se puede combinar con otra sentenciaSELECTla cual revelará todas las contraseñas:
'
union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
--
Si esta consulta (jugando con'y--) fuera asignada a una de las variables utilizadas en$consulta, despertaría a la consulta "monstruo".

Las sentecias UPDATE de SQL también son susceptibles a ataques. Estas consultas también están amenazadas por el corte y la anteposición de una consulta completamente nueva. El atacante podría juguetear con la cláusulaSET, aunque en este caso, debe poseer algo de información sobre los esquemas para manipular la consulta con éxito. Esta información puede adquirirse examinando los nombres de las variables del formulario, o sencillamente mediante la fuerza bruta. No hay muchas convenciones de nombres para campos que almacenen contraseñas o nombres de usuarios.

Ejemplo #3 Desde restablecer una contraseña ... hasta obtener más privilegios (cualquier servidor de bases de datos)

<?php
$consulta
="UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
?>
Pero si un usuario malicioso podría enviar el valor' or uid like'%admin%a$uidpara cambiar la contraseña del administrador, o simplemente cambiar$pwdajejeje', trusted=100, admin='yespara obtener más privilegios, entonces, la consulta se tornaría:
<?php

// $uid: ' or uid like '%admin%
$consulta="UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%';";

// $pwd: jejeje', trusted=100, admin='yes
$consulta="UPDATE usertable SET pwd='jejeje', trusted=100, admin='yes' WHERE
...;"
;

?>

Un ejemplo turbador de cómo se puede acceder a los comandos a nivel del sistema operativo en algunos equipos anfitriones de bases de datos.

Ejemplo #4 Atacar el sistema operativo que hospeda la base de datos (Servidor MSSQL)

<?php

$consulta
="SELECT * FROM products WHERE id LIKE '%$prod%'";
$resultado=mssql_query($consulta);

?>
Si un atacante envía el valora%' exec master..xp_cmdshell 'net user test testpass /ADD' --a$prod, la$consultaserá:
<?php

$consulta
="SELECT * FROM products
WHERE id LIKE '%a%'
exec master..xp_cmdshell 'net user test testpass /ADD' --%'"
;
$resultado=mssql_query($consulta);

?>
El servidor MSSQL ejecuta la sentencia SQL en el lote incluyendo un comando para añadir un usuario nuevo a la base de datos de cuentas local. Si esta aplicación estuviera ejecutándose comosay el servicio MSSQLSERVER se estuviera ejecutando con los privilegios suficientes, el atacante ahora podría tener una cuenta con la cual acceder a esta máquina.

Nota:

Algunos de los ejemplos citados están vinculados a un servidor de bases de datos específico. Esto no significa que un ataque similar sea imposible en otros productos. Su servidor de base de datos también podría ser vulnerable de otra manera.

Un ejemplo comprobado de los problemas con respecto a las inyecciones de SQL
Imagen cortesía de» xkcd

Técnicas de evitación

Pese a que pueda parecer obvio que un atacante debe tener al menos algún conocimiento de arquitecturas de bases de datos para poder realizar un ataque con éxito, la obtención de esta información suele ser muy sencilla. Por ejemplo, cuando la base de datos forma parte de un software de código abierto o disponible públicamente con una instalación predefinida, dicha información se encuentra completamente libre y utilizable. Esta información podría haber sido divulgada en proyectos de código cerrado (incluso si está codificada, ofuscada o compilada), o incluso por el propio código mediante la visualización de mensajes de error. Otros métodos incluyen el uso de nombres frecuentes de tablas y columnas. Por ejemplo, un formulario de inicio de sesión que utiliza una tabla 'usuarios' con los nombres de columna 'id', 'username', y 'password'.

Estos ataques se basan principalmente en explotar el código que no ha sido escrito teniendo en cuenta la seguridad. Nunca se ha de confiar en ningún tipo de entrada, especialmente la que viene del lado del cliente, aún cuando esta venga de un cuadro de selección, un campo oculto o una cookie. El primer ejemplo muestra cómo una inofensiva consulta puede causar desastres.

  • Nunca se conecte como superusuario o como propietario de la base de datos. Siempre utilice usuarios personalizados con privilegios muy limitados.
  • Emplee sentencias preparadas con variables vinculadas. Son proporcionadas porPDO,MySQLiy otras bibliotecas.
  • Compruebe si la entrada proporcionada tiene el tipo de datos previsto.PHPtiene un amplio rango de funciones para validar la entrada de datos, desde las más simples, encontradas enFunciones de variablesy enFunciones del tipo carácter(p.ej.,is_numeric(),ctype_digit()respectivamente), hasta el soporte paraExpresiones regulares compatibles con Perl.
  • Si la expresión espera una entrada numérica, considere verificar los datos con la funciónctype_digit(), o silenciosamente cambie su tipo utilizandosettype(), o emplee su representación numérica por medio desprintf().

    Ejemplo #5 Una forma más segura de componer una consulta para paginación

    <?php

    settype
    ($índice,'integer');
    $consulta="SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET$índice;";

    // Observe %d en el string de formato; el uso de %s podría no tener un resultado significativo
    $consulta=sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;",
    $índice);

    ?>

  • Si la capa de la base de datos no admite variables vinculadas, entrecomille cada valor no numérico proporcionado por el usuario que sea pasado a la base de datos con la función de escapado de cadenas específica de la base de datos (p.ej.mysql_real_escape_string(),sqlite_escape_string(), etc.). Las funciones genéricas comoaddslashes()son útiles solamente en un entorno muy específico (p.ej., MySQL en un juego de caracteres monobyte conNO_BACKSLASH_ESCAPESdeshabilitada), por lo que es mejor evitarlas.
  • Sea como sea, no muestre ninguna información específica de la base de datos, especialmente sobre el esquema. Vea tambiénNotificación de erroresyManejo de errores y funciones de registro.
  • Su pueden utilizar procedimientos almacenados y cursores previamente definidos para abstraer el acceso a datos para que los usuarios no tengan acceso directo a las tablas o vistas, aunque que esta solución tiene otros impactos.

Además, se puede beneficiar del registro de consultas, ya sea dentro de un script o mediante la base de datos en sí misma, si es que lo soporta. Obviamente, llevar un registro no previene los intentos dañinos, aunque puede ser útil para realizar un seguimiento de las aplicación que han sido eludidas. El registro no es útil por sí mismo, sino por la información que contiene. Normalmente cuantos más detalles, mejor.




Reportando errores

Con la seguridad de PHP, hay dos formas para reportar errores. Una es en beneficio, para incrementar la seguridad, y la otra es para perjudicar.

Una táctica estándar de ataque conlleva a perfilar un sistema; llenándolo de datos incorrectos, revisando los tipos y contextos de los errores que son devueltos. Esto le permite al atacante recolectar información acerca del servidor, para determinar posibles debilidades. Por ejemplo, si un atacante ha recogido información sobre una página basada en un envío previo, él podría intentar sobrescribir las variables, o modificarlas:

Ejemplo #1 Atacando variables con una página HTML personalizada

<form method="post" action="objetivodelataque?username=badfoo&amp;password=badfoo">
<input type="hidden" name="username" value="badfoo" />
<input type="hidden" name="password" value="badfoo" />
</form>

Los errores de PHP que normalmente son devueltos, pueden ser muy útiles para el desarrollador que está intentando depurar un script, indicando qué cosas, como por ejemplo, qué función o qué fichero de PHP falló, y el número de línea en donde la falla ocurrió. Toda esta es la información que puede ser explotada. Esto no es algo raro para un desarrollador de PHP que utilice las funcionesshow_source(),highlight_string(), ohighlight_file()como una medida de depuración, pero en un sitio en escena, esto puede exponer variables ocultas, sintáxis sin revisar, y otra información peligrosa. Es especialmente peligroso el código en ejecución de fuentes conocidas con manejadores de depuración incluidos, o utilizar técnicas comunes de depuración. Si los atacantes pueden determinar qué técnica en general usted está utilizando, ellos podrían tratar de usar fuerza bruta en una página, enviando varias cadenas comunes de depuración:

Ejemplo #2 Explotando variables comunes de depuración

<form method="post" action="objetivodelataque?errors=Y&amp;showerrors=1&amp;debug=1">
<input type="hidden" name="errors" value="Y" />
<input type="hidden" name="showerrors" value="1" />
<input type="hidden" name="debug" value="1" />
</form>

Sin importar el método de manejo de errores, la capacidad de probar errores en un sistema conlleva a proveer a un atacante con mas información.

Por ejemplo, el estilo común de un error genérico de PHP indica que un sistema ciertamente está ejecutando PHP. Si un atacante está en una página .html, y quiere probar qué motor hay tras de ese servidor (para buscar debilidades en el sistema), lo alimenta con datos erróneos que lo podrían habilitar a que determine que ese sistema fue construido con PHP.

El error de una función puede indicar ya sea, un sistema que puede estar ejecutando un motor específico de base de datos, o dar las pistas de cómo una página web puede estar programada o diseñada. Esto permite una investigación más profunda dentro de los puertos abiertos de la base de datos, o buscar errores específicos o debilidades en una página web. Pasando diferentes porciones de datos erróneos, por ejemplo, un atacante puede determinar el orden de autenticación en un script, (por medio del número de línea de los errores) como también probar exploits que pueden ser utilizados en diferentes ubicaciones del script.

Un error del sistema de archivos o un error general de PHP puede indicar qué permisos tiene el servidor web, así también la estructura y organización de ficheros en el servidor web. El código de error escrito por el desarrollador puede agravar este problema, conllevando a la explotación fácil de la, hasta entonces, información "oculta".

Hay tres grandes soluciones a este problema. La primera consiste en examinar todas las funciones, e intentar arreglar la mayoría de los errores. La segunda es deshabilitar completamente la notificación de errores de el código en ejecución. La tercera es utilizar las funciones de manejo de error propias de PHP para crear su propio manejador de errores. Dependiendo de su política de seguridad, puede ser que encuentre que las tres sean aplicables a su situación.

Una forma de detectar este problema por adelantado es hacer uso de la función propia de PHPerror_reporting(), para ayudarle a asegurar su código y encontrar el uso de variables que podrían ser peligrosas. Al probar su código, antes de distribuirlo, conE_ALL, usted puede encontrar rapidamente áreas donde sus variables pueden ser abiertas para envenenamiento o modificación en otras maneras. Una vez usted está listo para distribuirlo, debería deshabilitar completamente el reporte de errores poniendo el valor deerror_reporting()a 0, o apagar el visor de errores utilizando la opcióndisplay_errorsdel ficherophp.inipara aislar su código de ataques. Si decide hacer esto último, también debería definir la ruta de acceso a su archivo de registros utilizando la directivaerror_log, y ponerlog_errorsen "on".

Ejemplo #3 Buscando variables peligrosas con E_ALL

<?php
if ($usuario) {// No se ha inicializado o revisado antes de utilizar
$permitir_acceso=1;
}
if (
$permitir_acceso==1) {// Si la prueba anterior falla, los que no estén inicializados o comprobados antes de utilizar, tendrán acceso
readfile("/ruta/hacia/datos/altamente/sensibles/index.html");
}
?>



Datos Enviados por el Usuario

Las mayores debilidades de muchos programasPHPno son inherentes al lenguaje mismo, sino simplemente un problema generado cuando se escribe código sin pensar en la seguridad. Por esta razón, usted debería tomarse siempre el tiempo para considerar las implicaciones de cada pedazo de código, para averiguar el posible peligro involucrado cuando una variable inesperada es enviada.

Ejemplo #1 Uso Peligroso de Variables

<?php
// eliminar un archivo del directorio personal del usuario .. ¿o
// quizás de alguien más?

unlink($variable_malvada);

// Imprimir el registro del acceso... ¿o quizás una entrada de /etc/passwd?
fwrite($desc_archivo,$variable_malvada);

// Ejecutar algo trivial.. ¿o rm -rf *?
system($variable_malvada);
exec($variable_malvada);

?>

Usted debería examinar siempre, y cuidadosamente su código para asegurarse de que cualquier variable siendo enviada desde un navegador web sea chequeada apropiadamente, y preguntarse a sí mismo:

  • ¿Este script afectará únicamente los archivos que se pretende?
  • ¿Puede tomarse acción sobre datos inusuales o indeseados?
  • ¿Puede ser usado este script en formas malintencionadas?
  • ¿Puede ser usado en conjunto con otros scripts en forma negativa?
  • ¿Serán adecuadamente registradas las transacciones?

Al preguntarse adecuadamente estas preguntas mientras escribe su script, en lugar de hacerlo posteriormente, usted previene una desafortunada re-implementación del programa cuando desee incrementar el nivel de seguridad. Al comenzar con esta mentalidad, no garantizará la seguridad de su sistema, pero puede ayudar a mejorarla.

Puede que también desee considerar la deshabilitación de register_globals, magic_quotes, u otros parámetros convenientes que pueden causar confusión sobre la validez, fuente o valor de una determinada variable. Trabajar conPHPen modo error_reporting(E_ALL) también puede ayudarle a advertir variables que están siendo usadas antes de ser chequeadas o inicializadas (de modo que puede prevenir que datos inusuales produzcan operaciones inadvertidas).



Ocultar PHP

En general, la seguridad por ocultación es una de las formas más débiles de seguridad. Aunque en algunos casos, es aconsejable cada pequeño elemento extra de seguridad.

Unas cuantas técnicas simples pueden ayudar a ocultarPHP, posiblemente retrasando a un atacante que esté tratando de descubrir debilidades en el sistema. Al establecer expose_php aoffen el ficherophp.ini, se reduce la cantidad de información disponible.

Otra táctica es configurar servidores web como Apache para interpretar diferentes tipos de ficheros por medio dePHP, ya sea con una directiva de.htaccesso en el propio fichero de configuración de Apache. Así se pueden utilizar extensiones de ficheros engañosas:

Ejemplo #1 Ocultando PHP como si fuera otro lenguaje

# Hacer que el código de PHP parezca otro tipo de código
AddType application/x-httpd-php .asp .py .pl
U ocultarlo completamente:

Ejemplo #2 Utilizar tipos desconocidos para extensiones de PHP

# Hacer que el código de PHP parezca de tipo desconocido
AddType application/x-httpd-php .bop .foo .133t
U ocultarlo como códigoHTML, lo cual tiene un pequeño impacto de rendimiento debido a que todos los ficherosHTMLserán procesados por el motor dePHP:

Ejemplo #3 Utilizar tiposHTMLpara extensiones de PHP

# Hacer que el código de PHP parezca HTML
AddType application/x-httpd-php .htm .html
Para que esto funcione eficazmente, se debe cambiar el nombre de los ficherosPHPcon las extensiones de arriba. Si bien es una forma de seguridad por ocultamiento, es una medida preventiva menor con pocos inconvenientes.



Mantenerse al día

PHP, como cualquier otro sistema de tamaño considerable, está bajo constante escrutinio y mejoramiento. Cada nueva versión incluye con frecuencia cambios mayores y menores para mejorar la seguridad y reparar cualquier fallo, problemas de configuración, y otros asuntos que puedan afectar la seguridad y estabilidad global del sistema.

Como cualquier lenguaje y programa de script a nivel de sistema, la mejor estrategia es actualizar con frecuencia y mantenerse alerta sobre las últimas versiones y sus cambios.




Características


Autenticación HTTP con PHP

Con la funciónheader()se puede enviar un mensaje de"Autenticación requerida"al navegador del cliente para mostrar una ventana emergente donde introducir un usuario y una contraseña. Una vez introducidos estos datos, el URL que contiene el script de PHP será invocado de nuevo con lasvariables predefinidasPHP_AUTH_USER,PHP_AUTH_PWyAUTH_TYPEestablecidas al nombre de usuario, contraseña y tipo de autenticación, respectivamente. Estas variables se encuentran en el array$_SERVER. Se admiten ambos métodos de autenticación, 'Basic' y 'Digest' (desde PHP 5.1.0). Véase la funciónheader()para más información.

Un fragmento de un script de ejemplo que forzaría la autenticación en una página es el siguiente:

Ejemplo #1 Ejemplo de autenticación HTTP 'Basic'

<?php
if (!isset($_SERVER['PHP_AUTH_USER'])) {
header('WWW-Authenticate: Basic realm="Mi dominio"');
header('HTTP/1.0 401 Unauthorized');
echo
'Texto a enviar si el usuario pulsa el botón Cancelar';
exit;
} else {
echo
"<p>Hola{$_SERVER['PHP_AUTH_USER']}.</p>";
echo
"<p>Introdujo{$_SERVER['PHP_AUTH_PW']}como su contraseña.</p>";
}
?>

Ejemplo #2 Ejemplo de autenticación HTTP 'Digest'

Este ejemplo muestra cómo implementar un sencillo script de autenticación HTTP 'Digest'. Para más información lea el» RFC 2617.

<?php
$dominio
='Area restringida';

// usuario => contraseña
$usuarios= array('admin'=>'micontraseña','invitado'=>'invitado');


if (empty(
$_SERVER['PHP_AUTH_DIGEST'])) {
header('HTTP/1.1 401 Unauthorized');
header('WWW-Authenticate: Digest realm="'.$dominio.
'",qop="auth",nonce="'.uniqid().'",opaque="'.md5($dominio).'"');

die(
'Texto a enviar si el usuario pulsa el botón Cancelar');
}


// Analizar la variable PHP_AUTH_DIGEST
if (!($datos=analizar_http_digest($_SERVER['PHP_AUTH_DIGEST'])) ||
!isset(
$usuarios[$datos['username']]))
die(
'Credenciales incorrectas');


// Generar una respuesta válida
$A1=md5($datos['username'] .':'.$dominio.':'.$usuarios[$datos['username']]);
$A2=md5($_SERVER['REQUEST_METHOD'].':'.$datos['uri']);
$respuesta_válida=md5($A1.':'.$datos['nonce'].':'.$datos['nc'].':'.$datos['cnonce'].':'.$datos['qop'].':'.$A2);

if (
$datos['response'] !=$respuesta_válida)
die(
'Credenciales incorrectas');

// Todo bien, usuario y contraseña válidos
echo'Se ha identificado como: '.$datos['username'];


// Función para analizar la cabecera de autenticación HTTP
functionanalizar_http_digest($txt)
{
// Protección contra datos ausentes
$partes_necesarias= array('nonce'=>1,'nc'=>1,'cnonce'=>1,'qop'=>1,'username'=>1,'uri'=>1,'response'=>1);
$datos= array();
$claves=implode('|',array_keys($partes_necesarias));

preg_match_all('@('.$claves.')=(?:([\'"])([^\2]+?)\2|([^\s,]+))@',$txt,$coincidencias,PREG_SET_ORDER);

foreach (
$coincidenciasas$c) {
$datos[$c[1]] =$c[3] ?$c[3] :$c[4];
unset(
$partes_necesarias[$c[1]]);
}

return
$partes_necesarias?false:$datos;
}
?>

Nota:Sobre la compatibilidad

Hay que tener cuidado al codificar las líneas de cabeceras HTTP. Para garantizar la mayor compatibilidad con todos los clientes, la palabra 'Basic' debe escribirse con 'B' mayúscula, la cadena del dominio debe estar entre comillas dobles (no simples), y debería haber exactamente un espacio precediendo al código401de la línea de la cabeceraHTTP/1.0 401. Los parámetros de autenticación deben estar separados por comas, como se vió en el ejemplo de 'Digest' anterior.

En lugar de imprimir simplementePHP_AUTH_USERyPHP_AUTH_PWcomo se hizo en el ejemplo anterior, podría ser conveniente validar el usuario y la contraseña, tal vez enviando una consulta a una base de datos o buscando el usuario en un fichero dbm.

Cuidado con los navegadores Internet Explorer defectuosos. Parecen ser muy quisquillosos con el orden de las cabeceras. Por ahora, parece ser que el truco está en enviar la cabeceraWWW-Authenticateantes que la cabeceraHTTP/1.0 401.

Para prevenir que alguien escriba un script que revele la contraseña de una página que se autenticó con un mecanismo externo tradicional, las variables PHP_AUTH no se establecerán si la autenticación externa está habilitada para esa página en particular. Independientemente, se puede emplearREMOTE_USERpara identificar al usuario autenticado externamente. De este modo, se podrá usar$_SERVER['REMOTE_USER'].

Nota:Sobre la configuración

PHP utiliza la presencia de una directivaAuthTypepara determinar si una autenticación externa está en uso.

Observe, sin embargo, que lo anterior no impide que alguien que controle un URL no autenticado pueda robar contraseñas de URL autenticados en el mismo servidor.

Tanto Netscape Navigator como Internet Explorer borran la caché de autenticación de la ventana del navegador local para el dominio al recibr una respuesta 401 del servidor. Esto, en efecto, puede hacer que se cierre la sesión de un usuario, obligándolo a reintroducir su nombre de usuario y contraseña. Algunos utilizan esto para inicios de sesión «expiradas» o proveer un botón de «Cerrar sesión».

Ejemplo #3 Ejemplo de autenticación HTTP forzando un nuevo usuario/contraseña

<?php
functionautenticar() {
header('WWW-Authenticate: Basic realm="Sistema de autenticación de prueba"');
header('HTTP/1.0 401 Unauthorized');
echo
"Debe introducir un ID y contraseña de identificación válidos para acceder a este recurso\n";
exit;
}

if (!isset(
$_SERVER['PHP_AUTH_USER']) ||
(
$_POST['VistoAntes'] ==1&&$_POST['UsuarioAntiguo'] ==$_SERVER['PHP_AUTH_USER'])) {
autenticar();
} else {
echo
"<p>Bienvenido: ".htmlspecialchars($_SERVER['PHP_AUTH_USER']) ."<br />";
echo
"Antiguo: ".htmlspecialchars($_REQUEST['UsuarioAntiguo']);
echo
"<form action='' method='post'>\n";
echo
"<input type='hidden' name='VistoAntes' value='1' />\n";
echo
"<input type='hidden' name='UsuarioAntiguo' value=\"".htmlspecialchars($_SERVER['PHP_AUTH_USER']) ."\" />\n";
echo
"<input type='submit' value='Reautenticar' />\n";
echo
"</form></p>\n";
}
?>

El estándar de autenticaciónHTTP Basicno requiere este funcionamiento, por lo que no se debería depender de ello. Las pruebas conLynxhan mostrado queLynxno limpia las credenciales de autenticación con una respuesta 401 del servidor, por lo que al presionar «atrás» y luego «adelante» abrirá el recurso nuevamente mientras los requisitos de credenciales no hayan cambiado. Sin embargo, el usuario puede pulsar la tecla'_'para limpiar su información de autenticación.

Para que la Autenticación HTTP funcione en un servidor IIS con la versión CGI de PHP, se debe editar la configuracion de "Seguridad de directorios" de IIS: hacer clic en "Editar" y solo marcar "Acceso anónimo"; todos los demas campos deberían estar sin marcar.

Nota:Sobre IIS:
Para que funcione la Autenticación HTTP con IIS, la directiva de PHPcgi.rfc2616_headersdebe establecerse a0(el valor predeterminado).



'Cookies'

PHP tiene soporte para las «cookies» deHTTPde forma transparente. Las cookies son un mecanismo por el que se almacenan datos en el navegador remoto para monitorizar o identificar a los usuarios que vuelvan al sito web. Las cookies se pueden configurar con las funcionessetcookie()osetrawcookie(). Las cookies son parte de la cabeceraHTTP, por lo quesetcookie()será invocada antes de enviar cualquier otra salida al navegador. Esta es la misma limitación que tiene la funciónheader(). Se pueden utilizar lasfunciones del búfer de salidapara retrasar la salida del script hasta que se haya decidido si establecer o no alguna cookie o enviar cualquier otra cabecera.

Algunas cookies enviadas desde el cliente serán incluidas automáticamente en el array autoglobal$_COOKIEsivariables_ordercontiene "C". Para asignar varios valores a una sola cookie, simplemente se debe agregar[]al nombre de la cookie.

Para más detalles, incluyendo notas sobre errores de los navegadores, véanse las funcionessetcookie()ysetrawcookie().



Sesiones

El soporte para sesiones en PHP consiste en una manera de preservar ciertos datos a través de accesos posteriores, lo que permite crear aplicaciones más personalizadas y mejorar el atractivo de un sitio web. Toda la información está en la secciónReferencia de sesiones.



Manejo de XForms

» XFormsdefine una variante de los formularios web tradicionales que permite emplearla en una gran variedad de plataformas y navegadores o incluso en medios no tradicionales como los documentos PDF.

La primera diferencia principal en XForms es la forma de enviar el formulario al cliente.» XForms for HTML Authorscontiene una descripción detallada de cómo crear XForms; para el propósito de este tutorial únicamente veremos un ejemplo simple.

Ejemplo #1 Un formulario simple de búsqueda con XForms

<h:html xmlns:h="http://www.w3.org/1999/xhtml"
        xmlns="http://www.w3.org/2002/xforms">
<h:head>
 <h:title>Búsqueda</h:title>
 <model>
  <submission action="http://example.com/search"
              method="post" id="s"/>
 </model>
</h:head>
<h:body>
 <h:p>
  <input ref="q"><label>Buscar</label></input>
  <submit submission="s"><label>Ir</label></submit>
 </h:p>
</h:body>
</h:html>

El formulario anterior muestra una caja de entrada de texto (llamadaq), y un botón de envío. Al presionar este botón, el formulario se envía a la página indicada poraction.

Aquí es donde comienzan a verse las diferencias desde el punto de vista de la aplicación web. En un formulario normal de HTML, los datos serían enviados comoapplication/x-www-form-urlencoded; en el mundo de XForms, esta información es enviada como datos formateados enXML.

Si se elige trabajar con XForms, sería conveniente que los datos se obtuvieran comoXML. En tal caso, se puede examinar$HTTP_RAW_POST_DATApara encontrar el documentoXMLgenerado por el navegador, el cual se puede pasar al motor deXSLTo al analizador de documentos favorito.

Si no se está interesado en formatear los datos y solo se desea que se carguen en la variable$_POSTtradicional, se puede instruir al navegador del cliente para enviarlos comoapplication/x-www-form-urlencodedcambiando el atributomethodaurlencoded-post.

Ejemplo #2 Empleo de un Xform para rellenar$_POST

<h:html xmlns:h="http://www.w3.org/1999/xhtml"
        xmlns="http://www.w3.org/2002/xforms">
<h:head>
 <h:title>Búsqueda</h:title>
 <model>
  <submission action="http://example.com/search"
              method="urlencoded-post" id="s"/>
 </model>
</h:head>
<h:body>
 <h:p>
  <input ref="q"><label>Buscar</label></input>
  <submit submission="s"><label>Ir</label></submit>
 </h:p>
</h:body>
</h:html>

Nota:En el momento de escribir esto, muchos navegadores no admiten XForms. Compruebe la versión de su navegador si los ejemplos anteriores fallan.



Subida de ficheros

Tabla de contenidos


Subida con el método POST

Esta característica permite la subida de ficheros de texto y binarios. Con la autenticación de PHP y las funciones de manipulación de ficheros se tiene control completo sobre quién está autorizado a realizar una subida y qué hay que hacer con el fichero una vez subido.

PHP es capaz de recibir subidas de ficheros de cualquier navegador compatible con el RFC-1867.

Nota:Nota sobre configuraciones relacionadas

Véase también las directivasfile_uploads,upload_max_filesize,upload_tmp_dir,post_max_sizeymax_input_timedephp.ini

PHP también admite el método PUT para subir ficheros tal y como lo utilizan los clientesNetscape ComposeryAmayadel W3C. Véase elSoporte para el método PUTpara más detalles.

Ejemplo #1 Formulario para la subida de ficheros

Se puede construir una página de subida de ficheros creando un formulario especial parecido a este:

<!-- El tipo de codificación de datos, enctype, DEBE especificarse como sigue -->
<form enctype="multipart/form-data" action="__URL__" method="POST">
    <!-- MAX_FILE_SIZE debe preceder al campo de entrada del fichero -->
    <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
    <!-- El nombre del elemento de entrada determina el nombre en el array $_FILES -->
    Enviar este fichero: <input name="fichero_usuario" type="file" />
    <input type="submit" value="Enviar fichero" />
</form>

El__URL__del ejemplo anterior se debe sustituir y debe apuntar a un fichero de PHP.

El campo ocultoMAX_FILE_SIZE(medido en bytes) debe preceder al campo de entrada del fichero, siendo su valor el tamaño de fichero máximo aceptado por PHP. Se debe utilizar siempre este elemento del formulario, ya que evita a los usuarios la molestia de esperar a que un fichero grande sea transferido sólo para descubrir que falló la transferencia porque era demasiado grande. Hay que tener en cuenta que engañar a esta configuración en el lado del navegador es muy fácil; nunca dependa de que los ficheros que tengan un tamaño mayor sean bloqueados por esta característica. Es simplemente una característica conventiene para los usuarios en el lado cliente de la aplicación. No obstante, la configuración de PHP (en el lado del servidor) para un tamaño máximo no puede ser engañada.

Nota:

Asegúrese de que el formulario de subida de ficheros tiene el atributoenctype="multipart/form-data"o de lo contrario la subida de ficheros no funcionará.

El array global$_FILEScontendrá toda la información de los los ficheros subidos. Su contenido en el formulario del ejemplo es el siguiente. Observe que se asume el empleo del nombrefichero_usuariopara el fichero subido, tal como se utiliza en el script de ejemplo anterior. Este puede ser cualquier nombre.

$_FILES['fichero_usuario']['name']

El nombre original del fichero en la máquina del cliente.

$_FILES['fichero_usuario']['type']

El tipo MIME del fichero, si el navegador proporcionó esta información. Un ejemplo sería"image/gif". Este tipo MIME, sin embargo, no se comprueba en el lado de PHP y por lo tanto no se garantiza su valor.

$_FILES['fichero_usuario']['size']

El tamaño, en bytes, del fichero subido.

$_FILES['fichero_usuario']['tmp_name']

El nombre temporal del fichero en el cual se almacena el fichero subido en el servidor.

$_FILES['fichero_usuario']['error']

Elcódigo de errorasociado a esta subida.

Por omisión, los ficheros se almacenan en el directorio temporal predeterminado del servidor, a menos que se haya indicado otra ubicaicón con la directivaupload_tmp_direnphp.ini. Se puede cambiar el directorio predeterminado del servidor estableciendo la variable de entornoTMPDIRen el entorno en que se ejecuta PHP. Configurarlo usandoputenv()desde un script de PHP no funcionará. Esta variable de entorno también se puede utilizar para asegurarse de que las demás operaciones están trabajando sobre los ficheros subidos.

Ejemplo #2 Validación de la subida de ficheros

Véanse también las entradas de las funcionesis_uploaded_file()ymove_uploaded_file()para más información. El siguiente ejemplo procesará la subida de fichero desde un formulario.

<?php
$dir_subida
='/var/www/uploads/';
$fichero_subido=$dir_subida.basename($_FILES['fichero_usuario']['name']);

echo
'<pre>';
if (
move_uploaded_file($_FILES['fichero_usuario']['tmp_name'],$fichero_subido)) {
echo
"El fichero es válido y se subió con éxito.\n";
} else {
echo
"¡Posible ataque de subida de ficheros!\n";
}

echo
'Más información de depuración:';
print_r($_FILES);

print
"</pre>";

?>

El script de PHP que recibe el fichero subido debería implementar cualquier lógica necesaria para determinar qué se debe hacer con el fichero subido. Se puede, por ejemplo, utilizar la variable$_FILES['fichero_usuario']['size']para descartar cualquier fichero que sea demasiado pequeño o demasiado grande. Se podría utilizar la variable$_FILES['fichero_usuario']['type']para descartar cualquier fichero que no corresponda con un cierto criterio de tipo, aunque esto se debe emplear solo como la primera de una serie de comprobaciones debido a que este valor está completamente bajo el control del cliente y no se comprueba en el lado de PHP. También se puede usar$_FILES['fichero_usuario']['error']y planear la lógica de acuerdo con loscódigos de error. Cualquiera que sea la lógica, se debería borrar el fichero del directorio temporal o moverlo a otra ubicación.

Si no se selecciona ningún fichero en el formulario para realizar la subida, PHP devolverá$_FILES['fichero_usuario']['size']como 0, y$_FILES['fichero_usuario']['tmp_name']como ninguno.

El fichero será borrado del directorio temporal al final de la solicitud si este no ha sido movido o renombrado.

Ejemplo #3 Subir un array de ficheros

PHP admite lafuncionalidad de array en HTMLincluso con ficheros.

<form action="" method="post" enctype="multipart/form-data">
<p>Imágenes:
<input type="file" name="imágenes[]" />
<input type="file" name="imágenes[]" />
<input type="file" name="imágenes[]" />
<input type="submit" value="Enviar" />
</p>
</form>
<?php
foreach ($_FILES["imágenes"]["error"] as$clave=>$error) {
if (
$error==UPLOAD_ERR_OK) {
$nombre_tmp=$_FILES["imágenes"]["tmp_name"][$clave];
// basename() puede evitar ataques de denegació del sistema de ficheros;
// podría ser apropiado más validación/saneamiento del nombre de fichero
$nombre=basename($_FILES["imágenes"]["name"][$clave]);
move_uploaded_file($nombre_tmp,"datos/$nombre");
}
}
?>

Se puede implementar una barra de progreso de subida de ficheros con elProgreso de subida en sesiones.



Explicación de los mensajes de error

PHP devuelve un código de error apropiado junto con el array de ficheros. El código de error se puede encontrar en el segmentoerrordel array de ficheros que PHP crea durante la subida de ficheros. En otras palabras, el error puede encontrarse en$_FILES['fichero_usuario']['error'].

UPLOAD_ERR_OK

Valor: 0; No hay error, fichero subido con éxito.

UPLOAD_ERR_INI_SIZE

Valor: 1; El fichero subido excede la directivaupload_max_filesizedephp.ini.

UPLOAD_ERR_FORM_SIZE

Valor: 2; El fichero subido excede la directivaMAX_FILE_SIZEespecificada en el formulario HTML.

UPLOAD_ERR_PARTIAL

Valor: 3; El fichero fue sólo parcialmente subido.

UPLOAD_ERR_NO_FILE

Valor: 4; No se subió ningún fichero.

UPLOAD_ERR_NO_TMP_DIR

Valor: 6; Falta la carpeta temporal.

UPLOAD_ERR_CANT_WRITE

Valor: 7; No se pudo escribir el fichero en el disco.

UPLOAD_ERR_EXTENSION

Valor: 8; Una extensión de PHP detuvo la subida de ficheros. PHP no proporciona una forma de determinar la extensión que causó la parada de la subida de ficheros; el examen de la lista de extensiones cargadas conphpinfo()puede ayudar.



Dificultades comunes

El elementoMAX_FILE_SIZEno puede especificar un tamaño de fichero mayor que el establecido en la directivaupload_max_filesizedel ficherophp.ini. Por defecto es 2 megabytes.

Si hay un límite de memoria habilitado, podría ser necesario un valor dememory_limitmás grande. Asegúrese de establecer un valor dememory_limitlo suficientemente grande.

Si el valor demax_execution_timees demasiado pequeño, la ejecución del script podría exceder este valor. Asegúrese de establecer un valor demax_execution_timelo suficientemente grande.

Nota:max_execution_timesolo afecta al tiempo de ejecución del propio script. Todo tiempo empleado en actividades externas a la ejecución del script, tales como las llamadas al sistema consystem(), la funciónsleep(), las consultas a base de datos, el tiempo que tarda el proceso de subida de ficheros, etc., no se incluye para determinar el tiempo máximo que el script ha estado en ejecución.

Advertencia

max_input_timeestablece el tiempo máximo, en segundos, que al script se le permite recibir información; esto incluye la subida de ficheros. Para ficheros grandes o varios ficheros, o usuarios con conexiones más lentas, podría excederse el valor predeterminado de60 segundos.

Si el valor depost_max_sizese establece demasiado pequeño, los ficheros grandes no podrán ser subidos. Asegúrese de establecerpost_max_sizelo suficientemente grande.

El ajuste de configuraciónmax_file_uploadscontrola el número máximo de ficheros que se pueden subir en una petición. Si se suben más ficheros que el límite establecido,$_FILESparará de procesar ficheros una vez se alcance este límite. Por ejemplo, simax_file_uploadsse establece a10,$_FILESnunca contendrá más de 10 elementos.

No validar sobre qué fichero se opera podría significar que los usuarios pueden acceder a información delicada de otros directorios.

Por favor, observe que elCERN httpdparece quitar todo lo que empieza con primer espacio en blanco en la cabecera de tipo de contenido MIME que recibe desde el cliente. Mientras este sea el caso, elCERN httpdno tendrá soporte para la funcionalidad de subida de ficheros.

Debido a la gran cantidad de estilos de listados de directorios, no podemos garantizar que los ficheros con nombres exóticos (como el que contiene espacios en blanco) se manejen adecuadamente.

Los desarrolladores no deben mezclar los camposinputnormales con los de subida de ficheros en la misma variable de formulario (mediante un nombre deinputcomofoo[]).



Subida de varios ficheros

Se pueden subir varios ficheros utilizando diferentesnamepara losinput.

También es posible subir varios ficheros simultáneamente y tener la información organizada automáticamente en arrays. Para ello es necesario utilizar la misma sintaxis de presentación de array en el formulario HTML, tal como se hace con 'selects' y 'checkboxes' múltiples:

Ejemplo #1 Subida de varios ficheros

<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Enviar estos ficheros:<br />
  <input name="fichero_usuario[]" type="file" /><br />
  <input name="fichero_usuario[]" type="file" /><br />
  <input type="submit" value="Enviar ficheros" />
</form>

Cuando se envía el formulario de arriba, se inicializarán los arrays$_FILES['fichero_usuario'],$_FILES['fichero_usuario']['name']y$_FILES['fichero_usuario']['size']serán inicializados.

Por ejemplo, suponga que se envían los nombres de fichero/home/test/review.htmly/home/test/xwp.out. En este caso,$_FILES['fichero_usuario']['name'][0]contendría el valorreview.html, y$_FILES['fichero_usuario']['name'][1]contendría el valorxwp.out. De manera similar,$_FILES['fichero_usuario']['size'][0]contendría el tamaño del ficheroreview.html, y así sucesivamente.

También se establecen$_FILES['fichero_usuario']['name'][0],$_FILES['fichero_usuario']['tmp_name'][0],$_FILES['fichero_usuario']['size'][0], y$_FILES['fichero_usuario']['type'][0].

Advertencia

El ajuste de configuraciónmax_file_uploadsactúa como límite del número de ficheros que se pueden subir en una petición. Es necesario asegurarse de que el formulario no intente subir más ficheros que este límite en una petición.



Soporte para el método PUT

PHP ofrece soporte para el método PUT de HTTP utilizado por algunos clientes para almacenar ficheros en un servidor. Las peticiones PUT son mucho más simples que una subida de ficheros mediante peticiones POST. Se ven algo como esto:

PUT /ruta/nombrefichero.html HTTP/1.1

Esto normalmente significaría que el cliente remoto quiere guardar el contenido que le sigue como:/ruta/nombrefichero.htmlen el árbol web. Obviamente, no es una buena idea que Apache o PHP permitan a todo el mundo sobrescribir automáticamente cualquier fichero del árbol web. Por tanto, para manejar tales peticiones se debe primero indicar al servidor web que cierto script de PHP maneje la petición. En Apache, esto se hace con la directivaScript. Esta se puede colocar casi en cualquier parte del fichero de configuración de Apache. Un lugar común es dentro de un bloque<Directory>o tal vez dentro de un bloque<VirtualHost>. Una línea como ésta resolvería el problema:

Script PUT /put.php

Esto le indica a Apache que envíe todas las peticiones PUT para los URI que coincidan con el contexto en el cual se pone esta línea en el scriptput.php. Se asume, por supuesto, que se tiene habilitado PHP para la extensión.phpy que PHP está activo. El recurso de destino para todas las peiticiones PUT a este script tiene que ser el propio script, no el nombre de fichero que debería tener el fichero subido.

Entonces, con PHP se haría algo como lo siguiente en el fichero put.php. Se copiaría el contenido del fichero subido al ficheromificheroput.exten el servidor. Podría ser conveniente realizar algunas comprobaciones y/o autenticar al usuario antes de realizar esta copia del fichero.

Ejemplo #1 Guardar ficheros PUT de HTTP

<?php
/* Los datos de PUT vienen en el flujo de entrada estándar */
$datosPUT=fopen("php://input","r");

/* Abrir un fichero para escritura */
$fp=fopen("mificheroput.ext","w");

/* Leer 1 KB de datos cada vez
y escribir en el fichero */
while ($datos=fread($datosPUT,1024))
fwrite($fp,$datos);

/* Cerrar los flujos */
fclose($fp);
fclose($datosPUT);
?>





Empleo de ficheros remotos

Siempre queallow_url_fopenesté habilitado enphp.ini, se pueden usar los URL deHTTPyFTPcon la mayoría de las funciones que toman un nombre de fichero como parámetro. Además, los URL se pueden emplear con las sentenciasinclude,include_once,requireyrequire_once(desde PHP 5.2.0,allow_url_includedebe estar habilitado para ello). VéanseProtocolos y Envolturas soportadospara más información sobre los protocolos admitidos por PHP.

Por ejemplo, se puede emplear para abrir un fichero en un servidor web remoto, analizar la salida de los datos deseados, y usar dichos datos en una consulta a una base de datos, o simplemente para mostrarlos en un estilo que haga juego con el del sitio web.

Ejemplo #1 Obtener el título de una página remota

<?php
$fichero
=fopen("http://www.example.com/","r");
if (!
$fichero) {
echo
"<p>Imposible abrir el fichero remoto.\n";
exit;
}
while (!
feof($fichero)) {
$línea=fgets($fichero,1024);
/* Esto solo funciona si el título y sus etiquetas están en una línea */
if (preg_match("@\<title\>(.*)\</title\>@i",$línea,$salida)) {
$título=$salida[1];
break;
}
}
fclose($fichero);
?>

También se puede escribir en ficheros de un servidor FTP (siempre que se esté conectado como un usuario con los permisos de acceso correctos). Con este método solamente se pueden crear ficheros nuevos. Si se intenta sobreescribir un fichero que ya existe, la llamada a la funciónfopen()fallará.

Para conectarse como un usuario distinto a 'anonymous', es necesario especificar el nombre de usuario (y posiblemente la contraseña) dentro del URL, tal como 'ftp://usuario:contraseña@ftp.example.com/ruta/al/fichero'. (Se puede utilizar la misma sintaxis para acceder a ficheros medianteHTTPcuando se requiera autenticación básica).

Ejemplo #2 Almacenar datos en un servidor remoto

<?php
$fichero
=fopen("ftp://ftp.example.com/incoming/outputfile","w");
if (!
$fichero) {
echo
"<p>Imposible abrir el fichero remoto para escritura.\n";
exit;
}
/* Escribir los datos aqui. */
fwrite($fichero,$_SERVER['HTTP_USER_AGENT'] ."\n");
fclose($fichero);
?>

Nota:

Con el ejemplo anterior, se podría tener la idea de que se puede emplear esta técnica para escribir un fichero de registro remoto. Desafortunadamente esto no funcionaría porque la llamada a la funciónfopen()fallará si el fichero remoto ya existe. Para realizar registros distribuidos como ese, debería echar un vistazo asyslog().



Manejo de conexiones

Internamente, en PHP se mantiene un estado de conexión. Hay 4 posibles estados:

  • 0 - NORMAL
  • 1 - ABORTED
  • 2 - TIMEOUT
  • 3 - ABORTED y TIMEOUT

Cuando un script de PHP está ejecutándose normalmente está activo el estado NORMAL (normal). Si el cliente remoto se desconecta, se activa el indicador de estado ABORTED (abortada). Un cliente remoto se desconecta normalmente porque presiona su botón STOP. Si se alcanza el tiempo límite impuesto por PHP (véaseset_time_limit()), se activa el indicador de estado TIMEOUT (expirada).

Se puede decidir si se desea que un cliente que se desconecte ocasione que se aborte el script. Algunas veces es útil que los scripts se ejecuten hasta su finalización, incluso si ya no hay un navegador remoto recibiendo la salida. Sin embargo, el comportamiento predeterminado es que el script sea abortado cuando el cliente remoto se desconecte. Este comportamiento puede ser establecido a través de la directiva ignore_user_abort dephp.ini, así como a través de la directiva correspondiente de Apachephp_value ignore_user_abortdehttpd.conf, o con la funciónignore_user_abort(). Si se decide no indicarle a PHP que ignore que el usuario aborte y el usuario aborta, el script finalizará. La única excepción es si se tiene registrada una función de apagado conregister_shutdown_function(). Con una función de apagado, cuando el usuario remoto activa el botón STOP, la próxima vez que el script intente mostrar algo, PHP detectará que la conexión fue abortada, llamando así a la función de apagado. Esta función de apagado también se invoca al final del script cuando finaliza normalmente, así que para hacer algo diferente en caso de que un cliente se desconecte, se puede emplear la funciónconnection_aborted(). Esta función devolverátruesi la conexión fue abortada.

El script puede ser finalizado también por el temporizador de script incorporado. El tiempo predeterminado es de 30 segundos. Se puede cambiar con la directivamax_execution_timedephp.inio la correspondiente de Apachephp_value max_execution_timedehttpd.conf, así como con la funciónset_time_limit(). Cuando el temporizador expira, el script se abortará y, como el caso del cliente anterior que se desconectó, si la función de apagado ha sido registrada, será llamada. Dentro de esta función de apagado se puede comprobar si el tiempo de espera causó la llamada a la función de apagado invocando a la funciónconnection_status(). Esta función devolverá 2 si el tiempo de espera causó la llamada a la función de apagado.

Una cosa a observar es que los estados ABORTED y TIMEOUT pueden estar activados al mismo tiempo. Esto es posible si se le indica a PHP que ignore los abortos que ocasione el usuario. PHP notará de hecho que un usuario podría haber roto la conexión, pero el script se mantendrá ejecutándose. Si entonces se alcanza el límite de tiempo, será abortado y la función de apagado, si la hubiera, será llamada. En este punto se encontrará queconnection_status()devuelve 3.



Conexiones persistentes a bases de datos

Las conexiones persistentes son enlaces que no se cierran al finalizar la ejecución de un script. Cuando se solicita una conexión persistente, PHP comprueba si ya hay una idéntica (que ya estuviera abierta antes), utilizándola si existe. Si no, crea el enlace. Una conexión «idéntica» es una conexión que fue abierta por el mismo host, con el mismo usuario y la misma contraseña (donde sea aplicable).

Aquellos que no están plenamente familiarizados con la forma en que trabajan y distribuyen la carga los servidores web podrían confundir para qué sirven las conexiones persistentes. En particular, con ellasnose pueden abrir «sesiones de usuario» en un mismo enlace,nose puede construir una transacción eficiente y no hacen muchísimas otras cosas. De hecho, para ser sumamente precisos, las conexiones persistentes no proporcionanningunaotra funcionalidad que no fuera posible realizar con sus hermanas no persistentes.

¿Por qué?

Esto tiene que ver con la manera en que los servidores web funcionan. Existen tres formas en las cuales un servidor web puede generar páginas web usando PHP.

El primer método es emplear PHP como una «envoltura» CGI. Cuando se ejecuta de esta forma, se crea y se destruye una instancia del intérprete de PHP por cada solicitud de página (para una página de PHP) al servidor web. Debido a que esta instancia se destruye después de cada solicitud, cualquier recurso que adquiera (tal como un enlace a un servidor de base de datos SQL) es cerrado en la destrucción de dicha instancia. En este caso, no se gana nada utilizando conexiones persistentes: simplemente no persisten.

El segundo método, y más popular, es ejecutar PHP como módulo en un servidor web multiproceso, lo que actualmente solo incluye a Apache. Un servidor multiproceso normalmente tiene un proceso (el padre) que coordina un grupo de procesos (sus hijos) los cuales son los que realmente hacen el trabajo de servir páginas web. Cuando una solicitud proviene de un cliente, esta es cedida a uno de los hijos que no esté ya sirviendo a otro cliente. Esto significa que cuando el mismo cliente hace una segunda solicitud al servidor, esta podría ser servida por un proceso hijo diferente a la primera vez. Cuando se abre una conexión persistente, cada página que solicite servicios SQL puede reusar la misma conexión establecida al servidor SQL.

El último método es utilizar PHP como complemento para un servidor web multihilo. Actualmente, PHP tiene soporte para ISAPI, WSAPI, y NSAPI (en Windows), las cuales permiten usar PHP como un complemento en servidores multihilo como Nestcape FastTrack (iPlanet), Microsoft Internet Information Server (IIS), y O'Reilly's WebSite Pro. El comportamiento es esencialmente el mismo para el modelo multiproceso descrito antes.

Si las conexiones persistentes no tienen ninguna funcionalidad adicional, ¿para que son útiles?

La respuesta es extremadamente simple: Eficacia. Las conexiones persistentes son buenas si la sobrecarga para crear enlaces al servidor SQL es alta. Que esta sobrecarga sea realmente alta o no depende de muchos factores, como el tipo de base de datos que se emplea, si esta se encuentra en la misma computadora en la que está el servidor web, la carga de la máquina donde está el servidor SQL, etc. En resumidas cuentas, si la sobrecarga de una conexión es alta, las conexiones persistentes ayudan considerablemente, haciendo que un proceso hijo únicamente se conecte una vez durante su vida útil, en lugar de hacerlo cada vez que procese una página que requiera una conexión al servidor SQL. Esto significa que cada hijo que abra una conexión persistente tendrá su propia conexión persistente abierta al servidor. Por ejemplo, si se tienen 20 procesos hijos diferentes que ejecutan un script que realiza una conexión persistente al servidor SQL, se tendrán 20 conexiones diferentes al servidor SQL, una por cada hijo.

Observe, sin embargo, que esto puede tener algunos inconvenientes si se está usando una base de datos con un limite de conexiones que sea excedido por las conexiones persistentes hijas. Si la base de datos tiene un limite de 16 conexiones simultáneas, y en el curso de una sesión de un servidor ocupado 17 hilos hijos intentan conectarse, uno de ellos no será capaz de hacerlo. Si un script contiene errores que impidan el cierre de las conexiones (como un bucle infinito), la mencionada base de datos con solamente 16 conexiones podría saturarse rápidamente. Compruebe la documentación de su base de datos para obtener información sobre el manejo conexiones abandonadas o inactivas.

Advertencia

Hay un par de advertencias más a tener en cuenta cuando se utilizan conexiones persistentes. Una es que cuando se usan bloqueos de tablas con una conexión persistente, si el script por alguna razón no puede liberar el bloqueo, los scripts subsiguientes que empleen la misma conexión quedarán en espera indefinidamente, puediendo ser necesario reiniciar el servidor httpd o el servidor de la base de datos. Otra cosa es que cuando se usan transacciones, un bloque de las mismas también acarrearía al siguiente script que utiliza la conexión si la ejecución del script termina antes de que el bloque lo haga. En cualquier caso, se puede usarregister_shutdown_function()para registrar una función de limpieza para desbloquear las tablas o deshacer las transacciones. Mejor aún, evitar este problema por completo no usando conexiones persistentes en scripts que utilicen bloqueos de tablas o transacciones (aún se pueden usar en otros lugares).

Un resumen importante. Las conexiones persistentes fueron diseñadas para tener una correspondencia uno a uno con las conexiones normales. Esto significa quesiemprese pueden reemplazar las conexiones persistentes por conexiones no persistentes, no cambiando así la forma de funcionar un script. Estopodría(y probablemente lo hará) cambiar la eficacia del script, aunque no su funcionamiento.

Véanse tambiénibase_pconnect(),ociplogon(),odbc_pconnect(),oci_pconnect(),pfsockopen()ypg_pconnect().



PHP desde la línea de comandos

Tabla de contenidos


Introducción

El principal objetivo de la SAPI CLI es el desarrollo de aplicaciones de consola con PHP. En este capítulo se explican las diferencias que hay entre la SAPI CLI y otrasSAPI. Vale la pena aclarar queCLIyCGIsonSAPIdiferentes pese a que comparten la mayoría de características.

La SAPI CLI se habilita por omisión con--enable-cli, aunque puede deshabilitarse usando la opción--disable-clial ejecutar./configure.

Tanto el nombre, ubicación y presencia de los binarios deCLI/CGIdiferirán dependiendo de cómo se instale PHP en el sistema. Al ejecutarmakede manera predeterminada,CGIyCLIse construyen y ubican comosapi/cgi/php-cgiysapi/cli/phprespectivamente, en el directorio origen de PHP. Debe tenerse en cuenta que las dos se llamanphp. Lo que suceda durante la ejecución demake installdependerá de la línea de configuración. Si durante la configuración se elige unaSAPIde módulo, tal como apxs, o bien se usa la opción--disable-cgi, se copiaráCLIa{PREFIJO}/bin/phpal ejecutarmake install; de lo contrario se colocaráCGIahí. Por ejemplo, si se utiliza--with-apxsen la línea de configuración,CLIse copiaría a{PREFIJO}/bin/phpdurantemake install. Si se desea sobrescribir la instalación del binario deCGI, debe usarsemake install-clitrasmake install. Alternativamente se puede especificar--disable-cgien la línea de configuración.

Nota:

Ya que tanto--enable-clicomo--enable-cgiestán habilitadas predeterminadamente, el simple hecho de tener--enable-clien la línea de configuración no implica queCLIse copie como{PREFIJO}/bin/phpdurantemake install.

Desde PHP 5, en Windows el binario deCLIse distribuye en la carpeta principal con el nombre dephp.exe. La versiónCGIse distribuye comophp-cgi.exe. Además, se distribuye un ficherophp-win.exesi PHP se configuró con--enable-cli-win32. Este funciona igual que la versiónCLI, solo que no muestra ninguna salida y, por tanto, no proporciona ninguna consola.

Nota:¿Qué SAPI tengo?

Desde la consola, al escribirphp -vsabremos siphpesCGIoCLI. Véase también la funciónphp_sapi_name()y la constantePHP_SAPI.

Nota:

En Unix hay disponible una página delmanual escribiendoman phpen la terminal.



Diferencias respecto a otrasSAPIs

Principales diferencias de laSAPICLIrespecto a otrasSAPI:

  • A diferencia de laSAPICGI, no se envía ninguna cabecera a la salida.

    Pese a que laSAPICGItiene un mecanismo para suprimir las cabeceras HTTP, no existe un equivalente para habilitarlas en la SAPI CLI.

    Por omisión,CLIse inicia en modo silencioso, si bien se mantienen las opciones-qy--no-headerpor motivos de compatibilidad, de forma que pueda ser posible utilizar antiguos scriptsCGI.

    No se cambia el directorio de trabajo al del script (las opciones-Cy--no-chdirse mantienen por compatibilidad).

    Mensajes de error en texto plano (no se formatean enHTML).

  • Hay ciertas directivas dephp.inique se ignoran en la SAPI CLI debido a que no tienen sentido en un entorno de consola:

    Directivasphp.inianuladas
    DirectivaValor predeterminado en laSAPICLIComentario
    html_errorsfalseSu valor predeterminado esfalse, ya que puede resultar complicado leer mensajes de error en la consola cuando estos están mezclados con etiquetasHTMLno interpretadas.
    implicit_flushtrueEn un entorno de consola, es preferible que las salidas que procedan deprint,echoy y similares se muestren inmediatamente y no se mantenga en memoria intermedia. Aun así, es posible utilizaroutput bufferingpara postergar o manipular la salida estándar.
    max_execution_time0 (ilimitado)PHP, en un entorno de consola, tiende a utilizarse para una gama mucho más amplia de los propósitos típicos de scripts basados en web, y como éstos pueden ser de muy larga duración, el tiempo de ejecución máximo se establece a ilimitado.
    register_argc_argvtrue

    Establecer esta directiva atruesignifica que los scripts ejecutados mediante laSAPICLIsiempre tienen acceso aargc(número de argumentos que se le pasan a la aplicación) yargv(array con los argumentos en sí).

    Las variables de PHP$argcy$argvse establecen automáticamente al valor apropiado cuando se utiliza laSAPICLI. Esos valores se pueden encontrar también en el array$_SERVER, por ejemplo:$_SERVER['argv']

    output_bufferingfalse

    Aunque la directivaphp.iniestá codificada comofalse, las funciones delbuffer de salidasí están disponibles.

    max_input_timefalse

    CLIde PHP no tiene soporte para GET, POST o subidas de ficheros.

    Nota:

    Estas directivas no pueden ser inicializadas con otro valor desde el fichero de configuraciónphp.inio con un valor personalizado (si se especifica). Esta limitación se debe a que los valores son aplicados después que todos los ficheros de configuración han sido analizados. Sin embargo, sus valores pueden ser cambiados en tiempo de ejecución (aunque esto no es aplicable a todas ellas, comoregister_argc_argv).

    Nota:

    Se recomienda establecerignore_user_aborten scripts de línea de comandos. Para más información, consulteignore_user_abort().

  • Para facilitar el trabajo en entornos de consola, se definen varias constantes paraflujos de entrada/salida.

  • La SAPI CLInocambia el directorio actual a aquel en el que se encuentra el script ejecutado.

    Ejemplo #1 Ejemplo que muestra las diferencias respecto a laSAPICGI:

    <?php
    // Aplicación de pruebas llamada test.php
    echogetcwd(),"\n";
    ?>

    Al usar la versiónCGI, la salida es:

    $ pwd
    /tmp
    
    $ php -q otro_directorio/test.php
    /tmp/otro_directorio
    

    Esto muestra claramente que PHP cambia el directorio actual a aquel en que se encuentre el script ejecutado.

    Al usar la SAPI CLI se obtiene:

    $ pwd
    /tmp
    
    $ php -f otro_directorio/test.php
    /tmp
    

    Esto ofrece una gran flexibilidad a la hora de escribir herramientas de consola en PHP.

    Nota:

    LaSAPICGIadmite este comportamiento propio de la SAPI CLI mediante la opción-Cal ejecutarlo desde la línea de comandos.



Opciones de la línea de comandos

Se puede consultar en cualquier momento la lista de opciones de línea de comandos en el binario de PHP con el modificador-h:

Usage: php [opciones] [-f] <fichero> [--] [args...]
   php [opciones] -r <código> [--] [args...]
   php [opciones] [-B <código_inicial>] -R <código> [-E <código_final>] [--] [args...]
   php [opciones] [-B <código_inicial>] -F <fichero> [-E <código_final>] [--] [args...]
   php [opciones] -- [args...]
   php [opciones] -a

  -a                      Se ejecuta interactivamente.
  -c <ruta>|<fichero>     Busca el fichero php.ini en este directorio.
  -n                      No se usará el fichero php.ini.
  -d foo[=bar]            Define la entrada INI de foo con el valor 'bar'
  -e                      Generate información extendida para el depurador/perfilador.
  -f <fichero>            Analiza y ejecuta el <fichero>.
  -h                      Esta ayuda.
  -i                      Información de PHP.
  -l                      Solamente revisa la sintáxis (lint).
  -m                      Muestra lo compilado en módulos.
  -r <code>               Ejecuta el <código> PHP sin utilizar las etiquetas del script <?..?>.
  -B <código_inicial>     Ejecuta el <código_inicial> antes de procesar las líneas de entrada.
  -R <code>               Ejecuta el <código> PHP por cada línea de entrada.
  -F <file>               Analiza y ejecuta el <fichero> por cada línea de entrada.
  -E <código_final>       Ejecuta el <código_final> después de procesar todas las líneas de entrada.
  -H                      Oculta los argumentos pasados desde cualquier herramienta externa.
  -S <dirección>:<puerto> Ejecuta con el servidor web interno.
  -t <raíz_documento>     Especifica la raíz del documento <raíz_documento> para el servidor web interno.
  -s                      Salida de la fuente en sintáxis HTML resaltada.
  -v                      Número de versión.
  -w                      Salida de la fuente con espacios en blanco y comentarios subrayados.
  -z <fichero>            Carga un <fichero> con extensión de Zend.

  args...                 Argumentos pasados al script. Utilice argumentos con -- cuando el primer argumento
                          inicie con - o el script sea leído desde la entrada estándar stdin

  --ini                   Muestra los nombres de fichero de configuración.

  --rf <nombre>           Muestra información sobre la función <nombre>.
  --rc <nombre>           Muestra información acerca de la clase <nombre>.
  --re <nombre>           Muestra información acerca de la extensión <nombre>.
  --rz <nombre>           Muestra información acerca de la extensión Zend <nombre>.
  --ri <nombre>           Muestra la configuración para la extensión <nombre>.

Nota:

Las opciones-rBRFEH,--iniy--r[fcezi]sólo están disponibles enCLI.



Ejecutando ficheros PHP

Hay tres formas distintas de proveer a la SAPI CLI con código PHP para que sea ejecutado:

  1. Decirle a PHP que ejecute un determinado fichero.

    $ php mi_script.php
    
    $ php -f mi_script.php
    

    Ambas formas (usando o no el modificador-f) ejecutan el ficheromi_script.php. Nótese que no hay restricción sobre cuales ficheros puede ser ejecutado; en particular, el nombre del fichero no es necesario que tenga una extensión.php.

    Nota:

    Si se necesita proporcionar argumentos al script, utilizando el modificador-f, el primer argumento debe ser--.

  2. Pasar el código PHP para ejecutarlo directamente en la línea de comandos.

    $ php -r 'print_r(get_defined_constants());'
    

    Debe tomarse especial cuidado con respecto al uso de comillas y la sustitución de variables de la consola.

    Nota:

    Lea cuidadosamente el ejemplo: No hay etiquetas de inicio y fin. El modificador-rsimplemente no lo necesita. Si se usare, provocaría un error sintáctico.

  3. Proporcionar el código PHP a ejecutar a través de la entrada estándar (stdin).

    Esto ofrece la posibilidad de crear código PHP dinámicamente para pasárselo al binario, tal y como se ve en este ejemplo (ficticio):

    $ alguna_aplicacion | algun_filtro | php | sort -u > salida_final.txt
    
No se pueden combinar las tres formas para ejecutar código.

Como todas las aplicaciones de consola, el binario de PHP acepta un determinado número de argumentos, sin embargo un script PHP también puede recibirlos. El número de argumentos que pueden ser pasados a su script no está limitado por PHP (aunque la consola tiene un determinado número de caracteres límite; usualmente usted no alcanzará este límite). Los argumentos pasados al script están disponibles en el array global$argv. El primer índice (cero) siempre contiene el nombre del script como se llamó desde la línea de comandos. Nótese que, si el código es ejecutado en la línea utilizando el modificador de consola-r, el valor de$argv[0]será simplemente un guión medio-). Lo mismo aplica si el código es ejecutado por medio de una tubería desde la entrada estándarSTDIN.

Una segunda variable global,$argc, contiene el número de elementos en el arreglo$argv(peronoel número de argumentos pasados al script).

Dado que los argumentos que se pasan a un script no comienzan con el caracter-, no hay nada especial a tener en cuenta. Si se pasa a un script un argumento que comience por-provocará errores porque el intérprete de PHP pensará que debe manejarlo él, aún antes de ejecutar el script. Para prevenir esto, utilice el separador de lista de argumentos--. Una vez que PHP lea este separador, todos los argumentos que lo sigan se pasarán intactos al script.

# Esto no ejecutará el código dado, sino que mostrará el uso de PHP
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# Esto pasrá el argumento '-h' al script, impidiendo que PHP muestre su uso
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Sin embargo, en sistemas Unix, hay otra forma de usar PHP para scripts de consola. Se puede escribir un script en el que la primera línea comience con#!/usr/bin/php(sustitúyalo por la ruta a suCLIbinario de PHP si es diferente). El resto del fichero debería contener código PHP normal con las etiquetas usuales de inicio y fin de PHP. Una vez que se otorguen permisos de ejecución al fichero apropiadamente (p.ej.chmod +x test) el script podrá ejecutarse como cualquier otro script de consola o perl:

Ejemplo #1 Ejecutando un script PHP como un script de consola

#!/usr/bin/php
<?php
var_dump
($argv);
?>

Asumiendo que este fichero se llamatesty que está en el directorio actual, es posible hacer lo siguiente:

$ chmod +x test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

Tal y como puede verse, en este caso no hace falta tener cuidado al pasar al script parámetros que comienzan con-.

El ejecutable de PHP puede ser utilizado para ejecutar scripts de PHP que sean absolutamente independientes del servidor web. En sistemas Unix, los caracteres especiales#!(o conocido como "shebang") deben añadirse en la primera línea del script seguido de la ruta hacia el binario de PHP para que le indique autom[aticamente al sistema cual es el programa que debería ejecutar al script. En plataformas Windows puede asociarphp.exepara que funcione al hacer doble clic en ficheros con extensión.php, o se puede hacer un fichero por lotes para ejecutar el script mediante PHP. La primera línea especial "shebang" que se añade a un script para que funcione en Unix no interferirá en Windows (ya que está formateado como un comentario de PHP), así que pueden escribirse programas para plataformas independientes incluyéndose sin ningún problema. Más abajo puede encontrarse un ejemplo sencillo de cómo escribir un programa de línea de comandos en PHP.

Ejemplo #2 Script destinado a ejecutarse desde la línea de comandos (script.php)

#!/usr/bin/php
<?php

if ($argc!=2||in_array($argv[1], array('--help','-help','-h','-?'))) {
?>

Éste es un script PHP de línea de comandos con un parámetro.

Uso:
<?phpecho$argv[0];?><parámetro>

<parámetro> puede ser alguna palabra que desee
mostrar en pantalla. Con las opciones --help, -help, -h,
o -?, puede mostrarse esta ayuda.

<?php
} else {
echo
$argv[1];
}
?>

El script de arriba, incluye la primera línea especial "shebang" de Unix para indicar que este fichero debería ejecutarse por PHP. Puesto que aquí estamos trabajando con una versiónCLI, no se mostrarán cabecerasHTTP.

El programa comprueba primero que hay más de un parámetro (adicionalmente al nombre del script, el cual también es contado). Si no lo hay, o si el parámetro fuese--help,-help,-ho-?, se imprime el mensaje de ayuda, utilizando$argv[0]para escribir el nombre del script dinámicamente tal como se escribió en la línea de comandos. De otra manera, el parámetro es mostrado exactamente como se recibió.

Para ejecutar el script superior en Unix, debe otorgarle permisos de ejecución al fichero para hacerlo ejecutable, y llamarlo simplemente comoscript.php mostrar_estooscript.php -h. En Windows, se puede crear un fichero por lotes para lograr esta tarea:

Ejemplo #3 Fichero por lotes para ejecutar un script PHP en línea de comandos (script.bat)

@echo OFF
"C:\php\php.exe" script.php %*

Asumiendo que el programa superior se llamarascript.php, yCLIphp.exeestuviera enC:\php\php.exe, este fichero por lotes lo ejecutaría automáticamente con los parámetros que se le hayan pasado:script.bat mostrar_estooscript.bat -h.

Vea también la documentación de extensiónReadlinepara conocer más funciones que pueden ser utilizadas para mejorar las aplicaciones de línea de comandos en PHP.

Si está en Windows, puede configurar PHP para que no sea necesario añadir niC:\php\php.exeni la extensión.php, tal como se describe enPHP en Línea de Comandos en Microsoft Windows.



Flujos de entrada/salida

SAPI CLI define algunas constantes para flujos de E/S que simplifican la programación en línea de comandos.

Opciones de línea de comandos
OpciónOpción LargaDescripción
-a--interactive

Ejecutar PHP de forma interactiva. Para más información, consúltese la secciónConsola interactiva.

-b--bindpath

Ruta Ligada en modo de servidor FASTCGI externo (sólo enCGI).

-C--no-chdir

No cambiar el directorio del script (sólo enCGI).

-q--no-header

Modo silencioso. Elimina la salida de cabecerasHTTP(sólo enCGI).

-T--timing

Calcula el tiempo de ejecución del script unnúmerode veces (sólo enCGI).

-c--php-ini

Especifica ya sea un directorio en el que se busca aphp.inio bien un ficheroINIpersonalizado (que no tiene porqué llamarsephp.ininecesariamente), p.ej.:

$ php -c /directorio/propio/mi_script.php

$ php -c /directorio/propio/fichero-propio.ini mi_script.php

Si no se especifica esta opción, se busca el ficherophp.inien laslocalizaciones predeterminadas.

-n--no-php-ini

Ignorar por completo el ficherophp.ini.

-d--define

Establecer un valor predeterminado para cualquiera de las directivas de configuración permitidas enphp.ini. Ésta es la sintaxis:

 -d directiva_de_configuracion[=valor]
 

# Si se omite el valor, se establecerá un "1" a la directiva
$ php -d max_execution_time
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Si se pasa un valor vacío, se establecerá "" a la directiva
php -d max_execution_time=
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# Se pasará lo que haya tras el caracter '=' a la directiva de configuración
$  php -d max_execution_time=20
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php
        -d max_execution_time=doesntmakesense
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

-e--profile-info

Activa el modo de información expandida, para usar con un depurador/perfilador.

-f--file

Analiza y ejecuta el fichero proporcionado. El modificador-fes opcional y puede ser omitido - es suficiente con solo poner el nombre del fichero a ejecutar.

Nota:

Para pasar argumentos a un script, el primer argumento debe ser--, sino PHP los interpretará como opciones de PHP.

-h y -?--help y --usageMuestra una lista de opciones de línea de comandos, con descripciones de una línea sobre lo que hace.
-i--infoInvoca aphpinfo(), y muestra el resultado. Si PHP no funcionara correctamente, es aconsejable utilizarphp -ipara ver donde se muestre cualquier mensaje de error antes o en el lugar de las tablas de información. Tenga en cuenta que al usarse en modoCGIla salida es enHTMLy por lo tanto muy larga.
-l--syntax-check

Provee un método conveniente para realizar solamente una revisión de sintáxis del código proporcionado de PHP. En caso de éxito, se muestra el textoNo syntax errors detected in <filename>en la salida estándar y se devuelve un código de retorno0. Si fallara, se mostraría el textoErrors parsing <filename>, además del mensaje de error de análisis correspondiente en la salida estándar, y se retornaría el código-1.

Esta opción no encuentra errores fatales (como funciones no definidas). Utilice el modificador-fsi se desea también comprobar errores fatales.

Nota:

Esta opción no funciona junto con la opción-r.

-m--modules

Ejemplo #1 Muestra los módulos PHP y Zend incorporados (y habilitados)

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-r--run

Permite ejecutar PHP desde la línea de comandos. Las etiquetas de inicio y fin (<?phpy?>)no son necesariasy provocarán un error sintáctico si estuvieran presentes.

Nota:

Debe tenerse cuidado al usar PHP de esta forma para no colisionar con sustituciones de variables de línea de comandos hechas por la propia consola.

Ejemplo #2 Obteniendo un error sintáctico usando comillas dobles

$ php -r "$foo = get_defined_constants();"
PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

Parse error: syntax error, unexpected '=' in Command line code on line 1

El problema aquí es que sh/bash lleva a cabo una sustitución de variables incluso si estamos usando comillas dobles". Puesto que la variable$foono está definida, no se sustituye por nada, haciendo que el código real que se le pasa a la ejecución de PHP sea:

$ php -r " = get_defined_constants();"

La forma correcta sería usar comillas simples'. Las variables de texto en comillas simples no se sustituyen en sh/bash.

Ejemplo #3 Usando comillas simples para prevenir la sustitución de variables de la consola

$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=>
  int(1)
  ["E_WARNING"]=>
  int(2)
  ["E_PARSE"]=>
  int(4)
  ["E_NOTICE"]=>
  int(8)
  ["E_CORE_ERROR"]=>
  [...]

Si se está usando una consola diferente de sh/bash, es posible experimentar otros errores. Le animamos a enviar un informe de error a» https://github.com/php/php-src/issues. Tenga en cuenta que es muy fácil verse en problemas al tratar de utilizar variables (de la consola o de PHP) en código de línea de comandos, o al usar el caracter de barra invertida (\) para escapar caracteres, así que tome mucho cuidado haciendo eso. Ha sido advertido!

Nota:

-restá disponible en SAPI CLI, pero no enCGISAPI.

Nota:

Esta opción está pensada unicamente para código muy básico, así que algunas directivas de configuración (tales comoauto_prepend_fileyauto_append_file) se ignoran en este modo.

-B--process-begin

Código PHP a ejecutar antes de procesar la entrada. Añadido en PHP 5.

-R--process-code

Código PHP a ejecutar por cada línea de entrada. Añadido en PHP 5.

Hay dos variables especiales disponibles en este modo:$argny$argi.$argncontendrá la línea que PHP está procesando en un momento dado, mientras que$argicontendrá el número de línea.

-F--process-file

Fichero PHP a ejecutar por cada línea de entrada. Añadido en PHP 5.

-E--process-end

Código PHP a ejecutar tras procesar cada línea. Añadido en PHP 5.

Ejemplo #4 Usando las opciones-B,-Ry-Epara contar el número de líneas de un proyecto.

$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
Total Lines: 37328

-S--server

Inicia elservidor web interno. Disponible a partir de PHP 5.4.0.

-t--docrootEspecifiva la raíz del documento para elservidor web interno. Disponible a partir de PHP 5.4.0.
-s--syntax-highlight y --syntax-highlighting

Mostrar el código fuente destacando la sintaxis en color.

Esta opción utiliza los mecanismos internos de análisis del ficheros y escribe una versión HTML coloreada y la muestra en la salida estándar. Tenga en cuenta que todo lo que hace es generar un bloque de etiquetas HTML<code> [...] </code>, sin cabeceras HTML.

Nota:

Esta opción no puede funcionar junto con la opción-r.

-v--version

Ejemplo #5 Al usar-vobtenemos el nombre de laSAPIy la versión de PHP y Zend

$ php -v
PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies

-w--strip

Mostrar código fuente sin comentarios ni líneas en blanco.

Nota:

Esta opción no puede usarse junto con la opción-r.

-z--zend-extension

Carga una extensión Zend. Si sólo se proporciona un nombre de fichero, PHP trata de cargar la extensión en el directorio de bibliotecas por defecto de su sistema (normalmente se especifica en/etc/ld.so.confen sistemas Linux, por ejemplo). Si se proporciona un nombre de fichero con la ruta absoluta no se usarán las rutas de bibliotecas del sistema. Un nombre de fichero relativo que incluya algún directorio le indicará a PHP que sólo trate de cargar la extensión a partir del directorio actual.

 --ini

Mostrar el nombre del fichero de configuración y de los directorios analizados. Disponible desde PHP 5.2.3.

Ejemplo #6 Ejemplo de--ini

$ php --ini
Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
Scan for additional .ini files in: (none)
Additional .ini files parsed:      (none)

--rf--rfunction

Mostrar información de la función o método proporcionado (p.ej. número y nombre de los parámetros). Disponible desde PHP 5.1.2.

Esta opción sólo está disponible si se compiló PHP con soporte paraReflection.

Ejemplo #7 Uso básico de--rf

$ php --rf var_dump
Function [ <internal> public function var_dump ] {

  - Parameters [2] {
    Parameter #0 [ <requerido> $var ]
    Parameter #1 [ <opcional> $... ]
  }
}

--rc--rclass

Muestra información de la clase dada (lista de constantes, propiedades y métodos). Disponible desde PHP 5.1.2.

Esta opción sólo está disponible si se compiló PHP con soporte paraReflection.

Ejemplo #8 Ejemplo de--rc

$ php --rc Directory
Class [ <internal:standard> class Directory ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [0] {
  }

  - Methods [3] {
    Method [ <internal> public method close ] {
    }

    Method [ <internal> public method rewind ] {
    }

    Method [ <internal> public method read ] {
    }
  }
}

--re--rextension

Muestra información de la extensión dada (lista de opciones enphp.ini, funciones definidas, constantes y clases). Disponible desde PHP 5.1.2.

Esta opción sólo está disponible si se compiló PHP con soporte paraReflection.

Ejemplo #9 Ejemplo de--re

$ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {

  - Functions {
    Function [ <internal> function json_encode ] {
    }
    Function [ <internal> function json_decode ] {
    }
  }
}

--rz--rzendextension

Mostrar la información de configuración para la extensión Zend proporcionada (la misma información que es devuelta por la funciónphpinfo()). Disponible como parte de PHP 5.4.0.

--ri--rextinfo

Mostrar información de configuración de la extensión dada (la misma información que muestraphpinfo()). Disponible desde PHP 5.2.2. La información relevante está disponible usando "main" como nombre de extensión.

Ejemplo #10 Ejemplo de--ri

$ php --ri date

date

date/time support => enabled
"Olson" Timezone Database Version => 2009.20
Timezone Database => internal
Default timezone => Europe/Oslo

Directive => Local Value => Master Value
date.timezone => Europe/Oslo => Europe/Oslo
date.default_latitude => 59.930972 => 59.930972
date.default_longitude => 10.776699 => 10.776699
date.sunset_zenith => 90.583333 => 90.583333
date.sunrise_zenith => 90.583333 => 90.583333

Teniendo esto en cuenta, no es necesario abrir por ejemplo un flujo astderr, sino que puede usarse la constante en lugar del recurso de tipo flujo:

php -r 'fwrite(STDERR, "stderr\n");'
No es necesario cerrar explícitamente estos flujos, ya que se cierra automáticamente por PHP al finalizar el script.

Nota:

Estas constantes no están disponibles si se leyera el script PHP a partir destdin.



Consola interactiva

Desde PHP 5.1.0, SAPI CLI ofrece una consola interactiva si se usa con el modificador-ay PHP está compilado con la opción--with-readline.

Al usar la consola interactiva, se puede escribir directamente código PHP que se ejecuta al momento.

Ejemplo #1 Ejecutando código desde la consola interactiva

$ php -a
Interactive shell

php > echo 5+8;
13
php > function addTwo($n)
php > {
php { return $n + 2;
php { }
php > var_dump(addtwo(2));
int(4)
php >

La consola interactiva, además, proporciona autocompletado mediante el tabulador de funciones, constantes, nombres de clases, variables, llamadas a métodos estáticos y constantes de clases.

Ejemplo #2 Autocompletado con el tabulador

Al pulsar dos veces la tecla tabulador habiendo múltiples opciones de completados, se mostrará una lista con éstas:

php > strp[TAB][TAB]
strpbrk   strpos    strptime
php > strp

Cuando sólo hay una posible opción, sólo con pulsar una vez el tabulador se completará el resto de la línea:

php > strpt[TAB]ime(

También funciona el autocompletado para nombres que se han definido durante la sesión de consola interactiva:

php > $fooEsteEsUnNombreDeVariableMuyLargo = 42;
php > $foo[TAB]EsteEsUnNombreDeVariableMuyLargo

La consola interactiva almacena tu historial, al que se puede acceder usando las teclas arriba y abajo. El historial se almacena en el fichero~/.php_history.

Ya en PHP 5.4.0, la SAPI CLI provee las configuraciones dephp.ini,cli.pagerycli.prompt. La configuración decli.pagerpermite a un programa externo (tal comoless) para que funcione como un paginador para la salida en lugar de se desplegado directamente en la pantalla. Las configuraciones decli.promptpermite cambiar el indicador de ingreso de órdenesphp >.

In PHP 5.4.0 también fue posible establecer las configuraciones dephp.inien la shell interactiva utilizando una notación abreviada.

Ejemplo #3 Estableciendo configuraciones dephp.inien la shell interactiva

La configuración decli.prompt:

php > #cli.prompt=hola mundo :>
  hola mundo :>

Usando comillas simples inclinadas es posible ejecutar código PHP en el indicador de órdenes:

php > #cli.prompt=`echo date('H:i:s');` php >
  15:49:35 php > echo 'hola';
  hola
  15:49:43 php > sleep(2);
  15:49:45 php >

Establecer el paginador aless:

php > #cli.pager=less
  php > phpinfo();
  (salida desplegada en less)
  php >

La configuración decli.promptsoporta unas cuantas secuencias de escape:

Constantes específicas de CLI
ConstanteDescripción
STDIN

Flujo abierto astdin. Ahorra tener que abrirlo con

<?php
$stdin
=fopen('php://stdin','r');
?>
Si se desea leer una sola línea destdin, puede usarse
<?php
$line
=trim(fgets(STDIN));// lee una línea de STDIN
fscanf(STDIN,"%d\n",$number);// lee un número de STDIN
?>

STDOUT

Flujo abierto astdout. Ahorra tener que abrirlo con

<?php
$stdout
=fopen('php://stdout','w');
?>

STDERR

Flujo abierto astderr. Ahorra tener que abrirlo con

<?php
$stderr
=fopen('php://stderr','w');
?>

Secuencias de escape decli.prompt
Sequence:Description:
\eUtilizado para agregar colores al ingreso de órdenes. Un ejemplo podría ser\e[032m\v \e[031m\b \e[34m\> \e[0m
\vLa versión de PHP.
\bIndica cual bloque de PHP está dentro. Por ejemplo/*se usa para indicar que está dentro de un comentario multilineal. El alcance externo es denotado porphp.
\>Indica el caracter de ingreso de órdenes. El caracter predeterminado es>, pero cambia cuando la shell está dentro de un bloque indeterminado o una cadena. Los caracteres posibles son:' " { ( >

Nota:

Los ficheros que se han incluido en este modo medianteauto_prepend_fileyauto_append_filese analizan con algunas restricciones - p.ej. las funciones deben estar definidas antes de que se carguen.

Nota:

Laauto-cargano está disponible al usar PHP en modo interactivo enCLI.



Servidor web interno

Advertencia

Este servidor web ha sido diseñado para ayudar al desarrollo de aplicaciones. También puede ser útil para propósitos de prueba o para demostraciones de aplicaciones que se ejecutan en entornos controlados. No se pretende que sea un servidor web con todas las funciones. No debe ser utilizado en una red pública.

Desde PHP 5.4.0, la SAPI CLI provee un servidor web embebido.

El servidor web ejecuta solamente un único proceso monohilo, por lo que las aplicaciones PHP se detendrán si la solicitud está bloqueada.

Las peticiones de URI se sirven desde el actual directorio de trabajo donde PHP se inició, a menos que la opción -t sea utilizada para especificar una raíz de documentos explícita. Si una petición de URI no especifica un fichero, entonces el index.php o index.html que estén en el directorio dado serán devueltos. Si ninguno de los ficheros existen, la búsqueda de index.php e index.html continuará en el directorio padre y continuará así hasta encontrar uno de ello o se alcance el directorio raíz. Si se encuentra index.php o index.html, se devuelve este y $_SERVER['PATH_INFO'] se establece a la parte final del URI. De lo contrario se devuelve un código de respuesta 404.

Si un fichero PHP es proporcionado en la línea de comandos cuando se inicia el servidor web éste es tratado como un script "enrutador". El script es ejecutado al inicio de cada petición HTTP. Si este script devuelvefalse, entonces el recurso solicitado se devuelve tal cual está. De otra forma la salida del script se devuelve en el navegador.

Los tipos MIME estándar son devueltos para ficheros con extensiones: .3gp, .apk, .avi, .bmp, .css, .csv, .doc, .docx, .flac, .gif, .gz, .gzip, .htm, .html, .ics, .jpe, .jpeg, .jpg, .js, .kml, .kmz, .m4a, .mov, .mp3, .mp4, .mpeg, .mpg, .odp, .ods, .odt, .oga, .ogg, .ogv, .pdf, .pdf, .png, .pps, .pptx, .qt, .svg, .swf, .tar, .text, .tif, .txt, .wav, .webm, .wmv, .xls, .xlsx, .xml, .xsl, .xsd, y .zip.

Registro de cambios: Tipos MIME soportados (extensiones de ficheros)
VersiónDescripción
5.5.12.xml, .xsl, and .xsd
5.5.7.3gp, .apk, .avi, .bmp, .csv, .doc, .docx, .flac, .gz, .gzip, .ics, .kml, .kmz, .m4a, .mp3, .mp4, .mpg, .mpeg, .mov, .odp, .ods, .odt, .oga, .pdf, .pptx, .pps, .qt, .swf, .tar, .text, .tif, .wav, .wmv, .xls, .xlsx, y .zip
5.5.5.pdf
5.4.11.ogg, .ogv, and .webm
5.4.4.htm and .svg

Ejemplo #1 Iniciando el servidor web

$ cd ~/public_html
$ php -S localhost:8000

La terminal mostrará:

PHP 5.4.0 Servidor de desarrollo iniciado en Jueves Julio 21 10:43:28 2011
Escuchando en localhost:8000
La raíz de documentos es /home/usuario/html_público
Presione Ctrl-C para salir

Después de una petición de una URI para http://localhost:8000/ y http://localhost:8000/mi_script.html la terminal mostrará algo similar a:

PHP 5.4.0 Servidor de desarrollo iniciado en Jueves Julio 21 10:43:28 2011
Escuchando en localhost:8000
La raíz de documentos es /home/usuario/html_público
Presione Ctrl-C para salir.
[Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Petición leída
[Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Petición leída
[Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Petición leída
[Thu Jul 21 10:48:52 2011] ::1:39148 GET /mi_script.html - Petición leída
[Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Petición leída

Ejemplo #2 Iniciando con una raíz de documentos específica

$ cd ~/html_público
$ php -S localhost:8000 -t foo/

La terminal mostrará:

PHP 5.4.0 Servidor de desarrollo iniciado en Jueves Julio 21 10:50:26 2011
Escuchando en localhost:8000
La raíz de documentos es /home/usuario/html_público/foo
Presione Ctrl-C para salir

Ejemplo #3 Utilizando un Script enrutador

En este ejemplo, las peticiones a las imágenes se mostrarán, pero las peticiones a ficheros HTML mostrarán "Bienvenido a PHP":

<?php
// router.php
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/',$_SERVER["REQUEST_URI"])){
return
false;// servir la petición tal cual es.
}else {
echo
"<p>Bienvenido a PHP</p>";
}

?>
$ php -S localhost:8000 router.php

Ejemplo #4 Revisión del uso de la CLI del servidor web

Para reutilizar un framework de script enrutador durante el desarrollo con la CLI del servidor web server y luego con un servidor web en producción:

<?php
// router.php
if (php_sapi_name() =='cli-server') {
/* los activos de ruta estática y devolver falso */
}
/* seguir adelante con operaciones normales de index.php */
?>
$ php -S localhost:8000 router.php

Ejemplo #5 Manejando tipos de ficheros no soportados

Si necesita servir un recurso estático cuyo tipo MIME no es manejado por la CLI del servidor web, utilice:

<?php
// router.php
$path=pathinfo($_SERVER["SCRIPT_FILENAME"]);
if (
$path["extension"] =="el") {
header("Content-Type: text/x-script.elisp");
readfile($_SERVER["SCRIPT_FILENAME"]);
}
else {
return
FALSE;
}
?>
$ php -S localhost:8000 router.php

Ejemplo #6 Accediendo a la CLI del servidor web desde máquinas remotas

Puede hacer que el servidor web sea accesible en el puerto 8000 a cualquier interfaz con:

$ php -S 0.0.0.0:8000


Configuración INI

Opciones de configuración de la SAPI CLI
NombrePor defectoCambiableHistorial de cambios
cli_server.color"0"PHP_INI_ALLDisponible desde PHP 5.4.0.

He aquí una breve explicación de las directivas de configuración.

cli_server.colorboolean

Habilita el servidor web de desarrollo interno para usa la codificación de color ANSI en la salida del terminal.




Recolección de basura

Tabla de contenidos

Esta sección explica las ventajas del nuevo mecanismo de Recoleción de basura (GC por sus siglas en inglés de «Garbage Collection») de la versión 5.3 de PHP.


Introducción al contador de referencias

Una variable en PHP se almacena en un contenedor llamado "zval". Un contenedor zval contiene, además del tipo de la variable y su valor, dos bits adicionales de información. Al primero se le llama "is_ref" y contiene un valor booleano que indica si la variable es parte o no de un "conjunto de referencias". Con este bit, el motor de PHP sabe diferenciar entre variables normales y referencias. Puesto que PHP permite referencias definidas por el usuario, tal y como se crean con el operador &, un contenedor zval tiene también un mecanismo contador de referencias para optimizar el uso de memoria. Esta segunda pieza adicional de información, llamada "refcount", contiene el número de variables (también llamadas símbolos) que apuntan a este contenedor zval. Todos los símbolos se almacenan en una tabla de símbolos, de las cuales hay una por cada ámbito. Hay un ámbito para el script principal (es decir, el solicitado por el navegador), además de uno por cada función o método.

Se crea un contenedor zval al crear una nueva variable con un valor constante, como por ejemplo:

Ejemplo #1 Creación de un nuevo contenedor zval

<?php
$a
="nuevo string";
?>

En este caso, el nombre del nuevo símbolo,a, se crea en el ámbito actual y se crea un nuevo contenedor de variable con el tipostringy el valornuevo string. El bit "is_ref" se establece por omisión afalsedado que no se ha creado ninguna referencia en el espacio del usuario. "refcount" se establece a1, pues solo hay un símbolo que haga uso de este contenedor de variable. Tenga en cuenta que si "refcount" es1, "is_ref" siempre valdráfalse. Si tiene» Xdebuginstalado, puede mostrar esta información llamando axdebug_debug_zval().

Ejemplo #2 Mostrar información de zval

<?php
$a
="nuevo string";
xdebug_debug_zval('a');
?>

El resultado del ejemplo sería:

a: (refcount=1, is_ref=0)='nuevo string'

Al asignar esta variable a otro nombre de variable, se incrementará refcount.

Ejemplo #3 Incremento de refcount de un zval

<?php
$a
="nuevo string";
$b=$a;
xdebug_debug_zval('a');
?>

El resultado del ejemplo sería:

a: (refcount=2, is_ref=0)='nuevo string'

Aquí, refcount vale2, pues el mismo contenedor de variable está vinculado tanto poracomo porb. PHP es lo suficiente inteligente para no copiar el contenedor de variable en sí cuando no es necesario. Los contenedores de variables se destruyen cuando "refcount" llega a cero. "refcount" se decrementa en uno cuando alguno de los símbolos vinculados al contenedor de variable abandona su ámbito (p.ej. cuando finaliza una función) o cuando un símbolo es desasignado (p. ej., llamando aunset()). El siguiente ejemplo muestra esto:

Ejemplo #4 Decremento de refcount de zval

<?php
$a
="nuevo string";
$c=$b=$a;
xdebug_debug_zval('a');
$b=42;
xdebug_debug_zval('a');
unset(
$c);
xdebug_debug_zval('a');
?>

El resultado del ejemplo sería:

a: (refcount=3, is_ref=0)='nuevo string'
a: (refcount=2, is_ref=0)='nuevo string'
a: (refcount=1, is_ref=0)='nuevo string'

Si ahora llamáramos aunset($a);, el contenedor de variable, incluyendo tanto el tipo como el valor, se eliminarían de la memoría.

Tipos compuestos

Las cosas se complican con tipos compuestos tales comoarrays yobject. En lugar de un valor de tiposcalar, losarrays yobjects almacenan sus propiedades en su propia tabla de símbolos. Esto significa que el siguiente ejemplo crea tres contenedores zval:

Ejemplo #5 Crear un zval de tipoarray

<?php
$a
= array('meaning'=>'life','number'=>42);
xdebug_debug_zval('a');
?>

El resultado del ejemplo sería algo similar a:

a: (refcount=1, is_ref=0)=array (
   'meaning' => (refcount=1, is_ref=0)='life',
   'number' => (refcount=1, is_ref=0)=42
)

Gráficamente

Los zval de un array simple

Los tres contenedores zval son:a,meaning, ynumber. Se aplican reglas similares a la hora de incrementar y decrementar "refcounts". Abajo, añadimos otro elemento al array, y fijamos su valor al contenido de un elemento ya existente:

Ejemplo #6 Añadir un elemento existente a un array

<?php
$a
= array('meaning'=>'life','number'=>42);
$a['life'] =$a['meaning'];
xdebug_debug_zval('a');
?>

El resultado del ejemplo sería algo similar a:

a: (refcount=1, is_ref=0)=array (
   'meaning' => (refcount=2, is_ref=0)='life',
   'number' => (refcount=1, is_ref=0)=42,
   'life' => (refcount=2, is_ref=0)='life'
)

Gráficamente

Los zval de un array simple con una referencia

A partir de la salida de Xdebug, vemos que tanto el antiguo como el nuevo elemento del array apuntan a un contenedor zval cuyo "refcount" vale2. Pese a que Xdebug muestra dos contenedores zval con valor'life', son el mismo. La funciónxdebug_debug_zval()no muestra esto, aunque podria comprobarse mostrando también el puntero de memoria.

Eliminar un elemento del array es como eliminar un símbolo de un ámbito. Al hacerlo, el "refcount" del contenedor al que apunta el elemento del array se decrementa. De nuevo, cuando "refcount" alcanza cero, el contenedor de la variable se elimina de la memoria. Un ejemplo que muestra esto:

Ejemplo #7 Eliminar un elemento de un array

<?php
$a
= array('meaning'=>'life','number'=>42);
$a['life'] =$a['meaning'];
unset(
$a['meaning'],$a['number'] );
xdebug_debug_zval('a');
?>

El resultado del ejemplo sería algo similar a:

a: (refcount=1, is_ref=0)=array (
   'life' => (refcount=1, is_ref=0)='life'
)

Ahora, las cosas se vuelven interesantes si añadimos al propio array como elemento del array, como veremos en el siguiente ejemplo, en el que también usaremos el operador de referencia, ya que de lo contrario PHP crearía una copia:

Ejemplo #8 Añadir el propio array como elemento de sí mismo

<?php
$a
= array('one');
$a[] =&$a;
xdebug_debug_zval('a');
?>

El resultado del ejemplo sería algo similar a:

a: (refcount=2, is_ref=1)=array (
   0 => (refcount=1, is_ref=0)='one',
   1 => (refcount=2, is_ref=1)=...
)

Gráficamente

Los zval para un array que contiene una referencia circular

Puede verse que tanto la variable de tipo array (a) como el segundo elemento (1) apuntan ahora a un contenedor de variable que tiene un "refcount" de2. Los "..." mostrados arriba indican que hay una referencia cíclica, lo cual, por supuesto, significa que en este caso los "..." apuntan al array original.

Al igual que antes, al eliminar una variable se elimina el símbolo y el contador de referencias del contenedor de variable al que apunte se decrementa en uno. De modo que, si eliminamos la variable$adespués de ejecutar el código anterior, el contador de referencias del contenedor de variable al que apuntan tanto$acomo el elemento "1" se decrementa en uno, de "2" a "1". Se puede representar así:

Ejemplo #9 Eliminar$a

(refcount=1, is_ref=1)=array (
   0 => (refcount=1, is_ref=0)='one',
   1 => (refcount=1, is_ref=1)=...
)

Gráficamente

Los zval después de eliminar un array con referencia circular mostrando la fuga de memoria

Problemas de limpieza

Pese a que ya no hay ningún símbolo en ningún ámbito que apunte a esta estructura, esta no se puede limpiar ya que el elemento "1" del array todavía apunta al mismo array. Al no haber un símbolo externo que apunte a él, no hay forma por la que el usuario pueda eliminar esta estructura; por tanto tenemos una fuga de memoria. Afortunadamente, PHP limpiará esta estructura de datos al finalizar la petición, aunque hasta entonces esté ocupando un valioso espacio de memoria. Esta situación ocurre a menudo si se está implementando un algoritmo de análisis o en otras situaciones en las que un nodo hijo apunte de nuevo a un elemento "padre". Por supuesto, esta situación también puede suceder con objetos, donde es más frecuente que ocurra, ya que los objetos siempre se usan implícitamente por referencia.

Esto no debería ser un problema si sólo ocurre una o dos veces, pero si estas fugas de memoria suceden miles, o incluso millones de veces, lógicamente esto comenzaría a ser un problema. Es especialmente problemático en scripts de larga duración, tales como demonios donde básicamente nunca terminan las peticiones, o en un gran conjunto de pruebas unitarias. Esto último causó problemas al ejecutar las pruebas unitarias del componente Template de la biblioteca eZ Componentes. En algunos casos, podrían ser necesarios 2 GB de memoria que quizás no los tenga el servidor de pruebas.



Recolección de referencias cíclicas

Tradicionalmente, los mecanismos que contabilizan las referencias en memoria, tal como el que empleaba PHP anteriormente, fallaban al abordar las fugas de memoria de referencias cíclicas. Sin embargo, desde PHP 5.3.0 se implementa el algoritmo síncrono del artículo» Recolección de ciclos concurrentes en sistemas de contabilidad de referenciasque resuelve este asunto.

Una explicación detallada del funcionamiento del algoritmo queda más allá del objetivo de esta sección, aunque aquí explicaremos el mecanismo básico. Antes de nada, debemos establecer unas reglas básicas. Si se incrementa un refcount, este aún sigue en uso: no es basura. Si se decrementa el refcount y llega a cero, el zval puede liberarse. Esto significa que la recolección de ciclos sólo puede llevarse a cabo cuando un argumento refcount se decrementa a un valor que no sea cero. En segundo lugar, en un ciclo de recolección de basura, es posible averiguar qué partes son basura comprobando si se puede decrementar en uno sus refcount, para después comprobar cuáles zval poseen un refcount de cero.

Algoritmo de recolección de basura

Para evitar llamar a la comprobación de ciclos de basura en cada posible decremento de un refcount, el algoritmo lo que hace es pasar todas las posibles raíces (zvals) al "buffer raíz" (marcándolos en "púrpura"). También se asegura de que cada raíz de basura sólo finaliza una vez en el buffer. Únicamente cuando el buffer raíz está completo, comienza el mecanismo de recolección para todos los zval diferentes que haya en su interior. Véase el paso A en la figura anterior.

En el paso B, el algoritmo inicia una primera búsqueda en profundidad de todas las posibles raíces en las que decrementa por uno los refcount de los zval que encuentra, asegurándose de que no decrementa dos veces el mismo zval (marcándolo en "gris"). En el paso C, el algoritmo vuelve a llevar a cabo una búsqueda en profundidad dentro de cada nodo raíz, para volver a comprobar el refcount de cada zval. Si ve que el refcount es cero, se marca al zval en "blanco" (azul en la figura). Si es mayor que cero, deshace el decremento con una búsqueda en profundidad partiendo de ese punto, y se le vuelve a marcar en "negro". En el último paso (D), el algoritmo recorre el buffer raíz eliminando las raíces zval que haya, y a la vez, comprueba qué zvals se han marcado en "blanco" en el paso anterior. Todos los zval marcados en "blanco" se eliminarán.

Ahora que ya tiene un conocimiento básico de cómo funciona el algoritmo, volveremos atrás para ver cómo se integra esto en PHP. Por omisión, el recolector de basuras de PHP está habilitado. Hay, sin embargo, una directiva enphp.inique permite cambiar esto:zend.enable_gc.

Cuando el recolector de basura está habilitado, el algoritmo que busca ciclos, tal y como se ha descrito arriba, se ejecuta cada vez que se llena el buffer raíz. Éste tiene un tamaño fijo de 10.000 raíces posibles (se puede modificar esto cambiando la contanteGC_ROOT_BUFFER_MAX_ENTRIESenZend/zend_gc.cdel código fuente de PHP, y recompilando PHP). Cuando el recolector de basuras se deshabilita, no se ejecutará el algoritmo que busca ciclos. Sea como fuere, las posibles raíces seguirían registrándose en el buffer raíz, sin importar si el mecanismo recolector de basuras está habilitado en la configuración o no.

Si estando deshabilitado el mecanismo recolector de basuras se llenara el buffer raíz de posibles raíces, no se registraría al resto de raíces posibles, por lo que no llegarían a ser analizadas por el algoritmo. Si fueran parte de un ciclo de referencia circular, nunca se liberarían y podrían provocar una fuga de memoria.

La razón por la que se registran las posibles raíces estando deshabilitado el mecanismo es porque es más rápido registrarlas que comprobar en cada una de ellas si el mecanismo está habilitado. Sin embargo, el recolector de basuras y el propio mecanismo de análisis, sí puede conllevar una cantidad de tiempo considerable.

Ademas de poder cambiar la configuraciónzend.enable_gc, también es posible habilitar o deshabilitar el mecanismo recolector de basura llamando agc_enable()ogc_disable()respectivamente. La llamada a estas funciones tiene el mismo efecto que habilitar o deshabilitar el mecanismo en la propia configuración. También es posible forzar la recolección de ciclos incluso sin que esté lleno el buffer raíz. Para hacer esto, se puede usar la funcióngc_collect_cycles(). Esta función devuelve el número de ciclos que fueron recolectados por el algoritmo.

El motivo por el que es posible habilitar o deshabilitar el mecanismo, o iniciar los ciclos de recolección a mano, es porque podría haber determinadas partes de una aplicación que necesiten mucha precisión de tiempo. En estos casos, quizás no se desee que funcione el mecanismo recolector de basuras. Por supuesto, al deshabilitar el recolector de basuras en algunas partes del código, se corre el riesgo de provocar fugas de memoria, ya que algunas raíces podrían no caber en el buffer raíz. Por tanto, lo mas prudente sería llamar agc_collect_cycles()justo después de llamar agc_disable()para que libere la memoria ocupada por posibles raíces ya registradas en el buffer raíz. Esto deja por tanto un buffer vacío, de modo que queda más espacio para almacenar posibles raíces en el tiempo en que el mecanismo recolector de ciclos está deshabilitado.



Consideraciones acerca del Rendimiento

Como mencionamos en la sección anterior, la recolección de raíces tiene muy bajo impacto en el rendimiento, pero aquí es cuando comparamos PHP 5.2 contra PHP 5.3. Si bien la recolección de posibles raíces comparado con la no recolección, como en PHP 5.2, es más lenta, hay otras modificaciones en tiempo de ejecución en PHP 5.3 que impiden que esta pérdida de rendimiento en particular pueda siquiera apreciarse.

Hay dos principales sectores en los que el rendimiento se ve afectado. El primero es el uso reducido de memoria, y mientras que el segunda es la reducción en tiempo de ejecución cuando el mecanismo recolector de basura lleva a cabo la limpieza de memoria. Revisaremos estos dos asuntos.

Uso Reducido de Memoria

Antes de nada, la razón por la que se implementa el mecanismo recolector de basuras es para reducir el uso de memoria limpiando, una vez que se cumplen las condiciones, las variables de referencias circulares. En la implementación de PHP, esto sucede cuando el buffer raíz está lleno, o cuando se invoca la funcióngc_collect_cycles(). En el gráfico mostrado abajo, se muestra el uso de memoria tanto en PHP 5.2 como en 5.3, excluyendo la memoria base que el propio PHP ocupa al arrancar.

Ejemplo #1 Ejemplo de uso de memoria

<?php
classFoo
{
public
$var='3.14159265359';
}

$baseMemory=memory_get_usage();

for (
$i=0;$i<=100000;$i++ )
{
$a= newFoo;
$a->self=$a;
if (
$i%500===0)
{
echo
sprintf('%8d: ',$i),memory_get_usage() -$baseMemory,"\n";
}
}
?>
Comparación de uso de memoria entre PHP 5.2 y PHP 5.3

En este ejemplo didáctico, estamos creando un objeto en el que una propiedad enlaza de nuevo al propio objeto. Cuando la variable$adel script se reasigna en la siguiente iteración del bucle, típicamente ocurriría una fuga de memoria. En este caso, se fugan dos contenedores zval (el zval del objeto, y el zval de la propiead), pero sólo se encuentra una posible raíz: la variable que se desasignó. Tras 10.000 iteraciones, el buffer se llena (con un total de 10.000 posibles raíces), y se lanza el mecanismo recolector de basura y libera la memoria asociada con esas posibles raíces. Puede apreciarse claramente en el uso de memoria "dentado" de la gráfica para PHP 5.3. Tras las 10.000 iteraciones, el mecanismo libera la memoria asociada a las variables con referencias cíclicas. En este ejemplo, el propio mecanismo no debe hacer un gran trabajo, puesto que la estructura que produce la fuga es extremadamente sencilla. A partir del diagrama, se puede comprobar que el uso máximo de memoria en PHP 5.3 es en torno a 9 Mb, mientras que en PHP 5.2 el uso de memoria no para de aumentar.

Reducción en Tiempo de Ejecución

El segundo sector en el que el mecanismo recolector de basura influye en el rendimiento es en el tiempo que lleva a éste liberar la memoria "fugada". Para comprobar de cuánto estamos hablando, modificaremos ligeramente el script anterior para tener en cuenta un mayor número de iteraciones, y eliminaremos las figuras de uso de memoria intermedio. Este es el segundo script:

Ejemplo #2 Influencia en rendimiento de Recolector de Basuras

<?php
classFoo
{
public
$var='3.14159265359';
}

for (
$i=0;$i<=1000000;$i++ )
{
$a= newFoo;
$a->self=$a;
}

echo
memory_get_peak_usage(),"\n";
?>

Ejecutaremos dos veces este script, una con el ajustezend.enable_gchabilitado, y en la otra deshabilitado:

Ejemplo #3 Ejecutando el script anterior

time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php
# and
time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php

En la máquina de ejemplo, el primer comando parece llevar en torno a 10,7 segundos, mientras que al segundo comando le lleva 11,4. Esto es un incremento de en torno al 7%. Sin embargo, el uso máximo de memoria del script se ha reducido en un 98%, pasando de 931Mb a 10Mb. Esta prueba no es muy científica, ni siquiera representativa de aplicaciones reales, pero demuestra que el uso de memoria se beneficia del mecanismo recolector de basuras. Lo interesante es que para este script en particular el incremento es siempre del 7%, mientras que el ahorro de memoria aumenta a medida que se encuentran más referencias cíclicas en la ejecución del script.

Estadísticas Internas de PHP del Recolector de Basuras

Todavía es posible dar más información sobre cómo funciona el mecanismo recolector de basuras dentro de PHP. Pero para hacerlo, será necesario recompilar PHP para habilitar el código de análises y de recopilación de datos. Se tendrá que asignar a la variable de entornoCFLAGSel valor-DGC_BENCH=1antes de ejecutar./configurecon las opciones deseadas. La siguiente secuencia muestra cómo hacerlo:

Ejemplo #4 Recompilando PHP para habilitar el análisis del Recolector de Basuras

export CFLAGS=-DGC_BENCH=1
./config.nice
make clean
make

Al ejecutar el ejemplo que vimos arriba con el nuevo binario de PHP que hemos creado, veremos que se muestra el siguiente resultado tras la ejecución de PHP:

Ejemplo #5 Estadísticas de Recolección de Basuras

GC Statistics
-------------
Runs:               110
Collected:          2072204
Root buffer length: 0
Root buffer peak:   10000

      Possible            Remove from  Marked
        Root    Buffered     buffer     grey
      --------  --------  -----------  ------
ZVAL   7175487   1491291    1241690   3611871
ZOBJ  28506264   1527980     677581   1025731

Las estadísticas más informativas son las que se muestran en el primer bloque. Puede comprobarse que el mecanismo recolector de basuras se ejecutó 110 veces, y en total, se liberaron más de 2 millones de ubicaciones en memoria durante esas 110 ejecuciones. Puesto que el mecanismo recolector de ciclos se ha ejecutado al menos una vez, el "pico del buffer raíz" es siempre 10.000.

Conclusión

En general el recolector de basuras de PHP sólo provocará un retraso cuando el algoritmo recolector de ciclos funcione, mientras que en scripts normales (más pequeños) no habrá un impacto real en el rendimiento.

Sin embargo, en el caso en el que el mecanismo recolector de ciclos se ejecute para scripts normales, la reducción de memoria permitirá que puedan funcionar más scripts concurrentemente en el servidor, ya que en total no utilizarán mucha memoria.

Los beneficios son más evidentss en scripts de larga duración, tales como grandes suits de pruebas o scripts demonios. También en las aplicaciones» PHP-GTK, que generalmente suelen ejecutarse durante más tiempo que scripts para la Web; el nuevo mecanismo marcará la diferencia en cuanto a las fugas de memoria progresivas en el tiempo.




Rastreo Dinámico con DTrace

Tabla de contenidos


Introducción a PHP y DTrace

DTrace es un marco de rastreo de disponibilidad permanente, bajo consumo, y disponible en un gran número de plataformas incluyendo Solaris, Mac OS X, Oracle Linux y BSD. DTrace puede seguir el rastro del comportamiento del sistema operativo y la ejecución del programa del usuario. DTrace puede enseñar los valores de los argumentos y ser utilizados para inferir estadísticas de rendimiento. Los sondeos son monitorizados por scripts creados por el usuario, escritos en el programa de scripting DTrace D. Esto permite el análisis eficiente de puntos de datos.

Los sondeos en PHP que no son activamente monitorizados por scripts DTrace D del usuario no contienen código observado por lo cual no hay una degradación del rendimiento durante la ejecución normal de la aplicación. Los sondeos que estan siendo monitorizados incurren una perdida suficientemente baja para permitir monitorización con DTrace en entornos de producción activos.

PHP incorpora sondeos "User-level Statically Defined Tracing" (USDT) que son evaluados en tiempo de ejecución. Por ejemplo, cuando un script D está monitorizando unaentrada de función, cada ve que la función de PHP es llamada, dispararía el sondeo y el código de acción que ésta tiene asociado. Esta código de acción podría, por ejemplo, imprimir los argumentos del sondeo tales como lo ubicación del fichero con la función PHP, o podría contabilizar el número de veces que esta función fue llamada.

Sólo sondas PHP USDT son descritas aquí. Refierase a documentación externa sobre DTrace de sistema operativo para ver como puede DTrace ser usado para rastrear funciones arbitrarias, y como puede ser usado para rastrear el comportamiento del sistema operativo. Tenga en cuenta que no todas las funcionalidades de DTrace estan disponibles en todas las implementaciones de DTrace.

Las sondas estáticas de DTrace están incluidas en PHP 5.4. Previo a esto estaba incluidas via una extensión» PECL, que ahora ha quedado obsoleta.

Las sondas estáticas DTrace en PHP pueden alternativamente ser usadas con las herramientas de SystemTap en algunas distribuciones Linux.



Usando PHP y DTrace

PHP puede ser configurado con sondas estáticas DTrace en plataformas que soportan Rastreo Dinámico DTrace.

Configurando PHP para Sondas Estáticas DTrace

Refierase a la documentación externa específica par su plataforma para habilitar el soporte para rastreo DTrace en el sistema operativo. Por ejemplo, en Oracle Linux arranque con un kernel UEK3 y haga:

# modprobe fasttrap
# chmod 666 /dev/dtrace/helper

En lugar de utilizarchmod, usted podria utilizar una regla de paquete ACL para limitar acceso a los dispositivos a ciertos usuarios.

Compile PHP con el parámetro de configuración--enable-dtrace:

# ./configure --enable-dtrace ...
# make
# make install

Esto habilita las sondas estáticas en el núcleo de PHP. Cualquiera de las extensiones que ofrezcan sus propios sondeos deberán ser compiladas de forma separada como extensiones compartidas.

Sondeos Estáticos DTrace en el núcleo de PHP

Los siguientes sondeos estáticos están disponibles en PHP
Nombre del SondeoDescripción del SondeoArgumentos del Sondeo
request-startupSe dispara cuando comienza una petición.char *file, char *request_uri, char *request_method
request-shutdownSe dispara cuando se termina una petición.char *file, char *request_uri, char *request_method
compile-file-entrySe dispara cuando la compilación de un script comienza.char *compile_file, char *compile_file_translated
compile-file-returnSe dispara cuando la compilación de un script termina.char *compile_file, char *compile_file_translated
execute-entrySe dispara cuando un código de operación array está por ser ejecutado. Por ejemplo, se dispara en llamadas a funciones, includes, y continuaciones de resumes.char *request_file, intlineno
execute-returnSe dispara después de la ejecución de un código de operación array.char *request_file, intlineno
function-entrySe dispara cuando el motor de PHP entra a la llamada de una función o método.char *function_name, char *request_file, intlineno, char *classname, char *scope
function-returnSe dispara cuando el motor de PHP regresa de la llamada a una función o método.char *function_name, char *request_file, intlineno, char *classname, char *scope
exception-thrownSe dispara cuando una excepción es lanzada.char *classname
exception-caughtSe dispara cuando una excepción es capturada.char *classname
errorSe dispara cuando ocurre un error, sin importar el nivel deerror_reporting.char *errormsg, char *request_file, intlineno

Otras extensiones PHP pueden también tener otras sondas estáticas adicionales.

Listando Sondas Estáticas DTrace en PHP

Para listar todas las sondas disponibles, inicie un proceso PHP y ejecute:

# dtrace -l

La salida será similar a:

   ID   PROVIDER            MODULE                          FUNCTION NAME
   [ . . . ]
    4   php15271               php               dtrace_compile_file compile-file-entry
    5   php15271               php               dtrace_compile_file compile-file-return
    6   php15271               php                        zend_error error
    7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
    8   php15271               php     zend_throw_exception_internal exception-thrown
    9   php15271               php                 dtrace_execute_ex execute-entry
   10   php15271               php           dtrace_execute_internal execute-entry
   11   php15271               php                 dtrace_execute_ex execute-return
   12   php15271               php           dtrace_execute_internal execute-return
   13   php15271               php                 dtrace_execute_ex function-entry
   14   php15271               php                 dtrace_execute_ex function-return
   15   php15271               php              php_request_shutdown request-shutdown
   16   php15271               php               php_request_startup request-startup

La columna Proveedor consiste enphpy el id del proceso del proceso PHP que está ejecutandose.

Si el servidor web Apache está corriendo, el nombre del módulo será, por ejemplo,libphp5.so, y habría múltiples bloques de listado, uno por cada proceso Apache ejecutandose.

La columna Función se refiere los nombres internos de función de su implementación en C, donde cada proveedor está ubicado.

Si un proceso PHP no está ejecutandose, entonces ningún sondeo será mostrado.

DTrace con un ejemplo PHP

Este ejemplo muestra los conceptos básicos del lenguaje de scripting DTrace D.

Ejemplo #1all_probes.dpara monitorizar todos los Śondeos Estáticos en PHP con DTrace

#!/usr/sbin/dtrace -Zs

#pragma D option quiet

php*:::compile-file-entry
{
    printf("PHP compile-file-entry\n");
    printf("  compile_file              %s\n", copyinstr(arg0));
    printf("  compile_file_translated   %s\n", copyinstr(arg1));
}

php*:::compile-file-return
{
    printf("PHP compile-file-return\n");
    printf("  compile_file              %s\n", copyinstr(arg0));
    printf("  compile_file_translated   %s\n", copyinstr(arg1));
}

php*:::error
{
    printf("PHP error\n");
    printf("  errormsg                  %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
}

php*:::exception-caught
{
    printf("PHP exception-caught\n");
    printf("  classname                 %s\n", copyinstr(arg0));
}

php*:::exception-thrown
{
    printf("PHP exception-thrown\n");
    printf("  classname                 %s\n", copyinstr(arg0));
}

php*:::execute-entry
{
    printf("PHP execute-entry\n");
    printf("  request_file              %s\n", copyinstr(arg0));
    printf("  lineno                    %d\n", (int)arg1);
}

php*:::execute-return
{
    printf("PHP execute-return\n");
    printf("  request_file              %s\n", copyinstr(arg0));
    printf("  lineno                    %d\n", (int)arg1);
}

php*:::function-entry
{
    printf("PHP function-entry\n");
    printf("  function_name             %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
    printf("  classname                 %s\n", copyinstr(arg3));
    printf("  scope                     %s\n", copyinstr(arg4));
}

php*:::function-return
{
    printf("PHP function-return\n");
    printf("  function_name             %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
    printf("  classname                 %s\n", copyinstr(arg3));
    printf("  scope                     %s\n", copyinstr(arg4));
}

php*:::request-shutdown
{
    printf("PHP request-shutdown\n");
    printf("  file                      %s\n", copyinstr(arg0));
    printf("  request_uri               %s\n", copyinstr(arg1));
    printf("  request_method            %s\n", copyinstr(arg2));
}

php*:::request-startup
{
    printf("PHP request-startup\n");
    printf("  file                      %s\n", copyinstr(arg0));
    printf("  request_uri               %s\n", copyinstr(arg1));
    printf("  request_method            %s\n", copyinstr(arg2));
}

Este script utiliza la opción-Zendtrace, permitiendo que se ejecute aún cuando no hay procesos PHP ejecutandose. Si esta opción se hubiese omitido el script hubiese terminado inmediatamente porque no sabría que los sondeos a ser monitorizados realmente son válidos.

Este script rastrea todas las sondas estáticas del núcleo de PHP y puntos de muestreo a lo largo de la duración de un script PHP que esté corriendo:

# ./all_probes.d

Ejecuta un script o aplicación PHP. El script D de monitorización mostrará los argumentos de cada sondeo según vayan sucediendo.

Cuando la monitorización está completada, el script D puede ser terminado con^C.

En máquinas con múltiples-CPU el orden de los sondeos podría no aparecer secuencialmente. Esto depende de en que CPU fue procesado, y como los hilos se mueven a través de las CPUs. Mostrar la fecha y hora del sondeo ayudará a reducir la confusión, por ejemplo:

php*:::function-entry
{
      printf("%lld: PHP function-entry ", walltimestamp);
      [ . . .]
}



Usando SystemTap con Sondas Estáticas en PHP DTrace

En algunas distribuciones Linux, la utilidad de rastreo SystemTap puede ser usada para rastrear sondas estáticas en PHP. Esto está disponible con PHP 5.4.20 y PHP 5.5.

Instalando PHP con SystemTap

Instalar el paquete de desarrollo SD de SystemTap:

# yum install systemtap-sdt-devel

Instalar PHP con los sondeos de DTrace habilitados:

# ./configure --enable-dtrace ...
# make

Listando Sondeos Estáticos con SystemTap

Los sondeos estáticos en PHP pueden ser listados usandostap:

# stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

Esto produce la salida:

process("sapi/cli/php").provider("php").mark("compile__file__entry")
process("sapi/cli/php").provider("php").mark("compile__file__return")
process("sapi/cli/php").provider("php").mark("error")
process("sapi/cli/php").provider("php").mark("exception__caught")
process("sapi/cli/php").provider("php").mark("exception__thrown")
process("sapi/cli/php").provider("php").mark("execute__entry")
process("sapi/cli/php").provider("php").mark("execute__return")
process("sapi/cli/php").provider("php").mark("function__entry")
process("sapi/cli/php").provider("php").mark("function__return")
process("sapi/cli/php").provider("php").mark("request__shutdown")
process("sapi/cli/php").provider("php").mark("request__startup")

SystemTap con un ejemplo PHP

Ejemplo #1all_probes.stppara monitorizar todas los Sondeos Estáticos de PHP con SystemTap

probe process("sapi/cli/php").provider("php").mark("compile__file__entry") {
    printf("Probe compile__file__entry\n");
    printf("  compile_file %s\n", user_string($arg1));
    printf("  compile_file_translated %s\n", user_string($arg2));
}
probe process("sapi/cli/php").provider("php").mark("compile__file__return") {
    printf("Probe compile__file__return\n");
    printf("  compile_file %s\n", user_string($arg1));
    printf("  compile_file_translated %s\n", user_string($arg2));
}
probe process("sapi/cli/php").provider("php").mark("error") {
    printf("Probe error\n");
    printf("  errormsg %s\n", user_string($arg1));
    printf("  request_file %s\n", user_string($arg2));
    printf("  lineno %d\n", $arg3);
}
probe process("sapi/cli/php").provider("php").mark("exception__caught") {
    printf("Probe exception__caught\n");
    printf("  classname %s\n", user_string($arg1));
}
probe process("sapi/cli/php").provider("php").mark("exception__thrown") {
    printf("Probe exception__thrown\n");
    printf("  classname %s\n", user_string($arg1));
}
probe process("sapi/cli/php").provider("php").mark("execute__entry") {
    printf("Probe execute__entry\n");
    printf("  request_file %s\n", user_string($arg1));
    printf("  lineno %d\n", $arg2);
}
probe process("sapi/cli/php").provider("php").mark("execute__return") {
    printf("Probe execute__return\n");
    printf("  request_file %s\n", user_string($arg1));
    printf("  lineno %d\n", $arg2);
}
probe process("sapi/cli/php").provider("php").mark("function__entry") {
    printf("Probe function__entry\n");
    printf("  function_name %s\n", user_string($arg1));
    printf("  request_file %s\n", user_string($arg2));
    printf("  lineno %d\n", $arg3);
    printf("  classname %s\n", user_string($arg4));
    printf("  scope %s\n", user_string($arg5));
}
probe process("sapi/cli/php").provider("php").mark("function__return") {
    printf("Probe function__return: %s\n", user_string($arg1));
    printf(" function_name %s\n", user_string($arg1));
    printf("  request_file %s\n", user_string($arg2));
    printf("  lineno %d\n", $arg3);
    printf("  classname %s\n", user_string($arg4));
    printf("  scope %s\n", user_string($arg5));
}
probe process("sapi/cli/php").provider("php").mark("request__shutdown") {
    printf("Probe request__shutdown\n");
    printf("  file %s\n", user_string($arg1));
    printf("  request_uri %s\n", user_string($arg2));
    printf("  request_method %s\n", user_string($arg3));
}
probe process("sapi/cli/php").provider("php").mark("request__startup") {
    printf("Probe request__startup\n");
    printf("  file %s\n", user_string($arg1));
    printf("  request_uri %s\n", user_string($arg2));
    printf("  request_method %s\n", user_string($arg3));
}

El script anterior rastreará todas las sondas estáticas del núcleo de PHP y puntos de muestreo a lo largo de la duración de un script PHP que esté corriendo:

# stap -c 'sapi/cli/php test.php' all_probes.stp





Referencia de funciones

Sugerencia

Ver tambiénCategorización de Extensiones.


Afecta el comportamiento de PHP


APC User Cache


Introducción

APCu es APC despojado del almacenamiento en caché del código de operación.

La primera base de código de APCu tenía la versión 4.0.0, y se bifurcó de la rama principal de APC en ese momento.

El soporte para PHP 7 está disponible a partir de APCu 5.0.0.

APCu puede proporcionar un modo de compatibilidad, de modo que pueda proporcionar una caída en reemplazo para las partes aplicables de APC.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

Si se requiere retrocompatibilidad con las partes de APC aplicables APCu debe configurarse con la opción --enable-apcu-bc.

Advertencia

PHP 7 tiene un módulo aparte (» apc.so) para la retrocompatibilidad con APC.

En el modo de retrocompatibilidad, APCu registra las funciones de APC aplicables con prototipos retrocompatibles.

Si una función de APC aceptabacache_type, la ignora simplemente la versión retrocompatible, and omitted from the prototype for the APCu version.

Nota:En Windows, APC necesita una ruta temporal donde ubicarse, y debe ser escribible por el servidor web. Comprueba las variables de entorno TMP, TEMP y USERPROFILE, en este orden, y finalmente intenta el directorio WINDOWS si ninguno de los anteriores está establecido.

Nota:Para detalles de implementación más profundos y altamente téctino, veáse el»  fichero TECHNOTES porporcionado por el desarrollador.

Los ficheros fuentes de APCu se pueden encontrar» aquí.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Although the default APCu settings are fine for many installations, serious users should consider tuning the following parameters.

There is one decision to be made configuring APCu. How much memory is going to be allocated to APCu. The ini directive that controls this isapc.shm_sizeRead the sections on this carefully below.

Once the server is running, theapc.phpscript that is bundled with the extension should be copied somewhere into the docroot and viewed with a browser as it provides a detailed analysis of the internal workings of APCu. If GD is enabled in PHP, it will even display some interesting graphs.

If APCu is working, theCache full countnumber (on the left) will display the number of times the cache has reached maximum capacity and has had to evict entries to free up memory. During eviction, ifapc.ttlwas specified, APCu will first attempt to remove expired entries, i.e. entries whose TTL has either expired, or entries that have no TTL set and haven't been accessed in the lastapc.ttlseconds. Ifapc.ttlwas not set, or removing expired entries did not free up enough space, APCu will clear the entire cache.

The number of evictions should be minimal in a well-configured cache. If the cache is constantly being filled, and thusly forcefully freed, the resulting churning will have disparaging effects on script performance. The easiest way to minimize this number is to allocate more memory for APCu.

When APCu is compiled with mmap support (Memory Mapping), it will use only one memory segment, unlike when APCu is built with SHM (SysV Shared Memory) support that uses multiple memory segments. MMAP does not have a maximum limit like SHM does in/proc/sys/kernel/shmmax. In general MMAP support is recommended because it will reclaim the memory faster when the webserver is restarted and all in all reduces memory allocation impact at startup.

APCu configuration options
NombrePor defectoCambiableHistorial de cambios
apc.enabled"1"PHP_INI_SYSTEM 
apc.shm_segments"1"PHP_INI_SYSTEM 
apc.shm_size"32M"PHP_INI_SYSTEM 
apc.entries_hint"4096"PHP_INI_SYSTEM 
apc.ttl"0"PHP_INI_SYSTEM 
apc.gc_ttl"3600"PHP_INI_SYSTEM 
apc.mmap_file_maskNULLPHP_INI_SYSTEM 
apc.slam_defense"1"PHP_INI_SYSTEM 
apc.enable_cli"0"PHP_INI_SYSTEM 
apc.use_request_time"0"PHP_INI_ALLPrior to APCu 5.1.19, the default was "1".
apc.serializer"php"PHP_INI_SYSTEMPrior to APCu 5.1.15, the default was "default".
apc.coredump_unmap"0"PHP_INI_SYSTEM 
apc.preload_pathNULLPHP_INI_SYSTEM 
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

apc.enabledbool

apc.enabledcan be set to 0 to disable APC. This is primarily useful when APC is statically compiled into PHP, since there is no other way to disable it (when compiled as a DSO, theextensionline inphp.inican just be commented-out).

apc.shm_segmentsint

The number of shared memory segments to allocate for the compiler cache. If APC is running out of shared memory butapc.shm_sizeis set as high as the system allows, raising this value might prevent APC from exhausting its memory.

apc.shm_sizestring

The size of each shared memory segment given by a shorthand notation as described inthis FAQ. By default, some systems (including most BSD variants) have very low limits on the size of a shared memory segment.

apc.entries_hintint

A "hint" about the number of distinct variables that might be stored. Set to zero or omit if not sure.

apc.ttlint

Consider cache entries without an explicit TTL to be expired if they have not been accessed in this many seconds. Effectively, this allows such entries to be removed opportunistically during a cache insert, or prior to a full expunge. Note that because removal is opportunistic, entries can still be readable even if they are older thanapc.ttlseconds. This setting has no effect on cache entries that have an explicit TTL specified.

apc.gc_ttlint

The number of seconds that a cache entry may remain on the garbage-collection list. This value provides a fail-safe in the event that a server process dies while executing a cached source file; if that source file is modified, the memory allocated for the old version will not be reclaimed until this TTL reached. Set to zero to disable this feature.

apc.mmap_file_maskstring

If compiled with MMAP support by using--enable-mmapthis is the mktemp-style file_mask to pass to the mmap module for determining whether your mmap'ed memory region is going to be file-backed or shared memory backed. For straight file-backed mmap, set it to something like/tmp/apc.XXXXXX(exactly 6Xs). To use POSIX-style shm_open/mmap put a.shmsomewhere in your mask. e.g./apc.shm.XXXXXXYou can also set it to/dev/zeroto use your kernel's/dev/zerointerface to anonymous mmap'ed memory. Leaving it undefined will force an anonymous mmap.

apc.slam_defenseint

On very busy servers whenever you start the server or modify files you can create a race of many processes all trying to cache the same file at the same time. This option sets the percentage of processes that will skip trying to cache an uncached file. Or think of it as the probability of a single process to skip caching. For example, settingapc.slam_defenseto75would mean that there is a 75% chance that the process will not cache an uncached file. So, the higher the setting the greater the defense against cache slams. Setting this to0disables this feature.

apc.enable_cliint

Mostly for testing and debugging. Setting this enables APC for the CLI version of PHP. Under normal circumstances, it is not ideal to create, populate and destroy the APC cache on every CLI request, but for various test scenarios it is useful to be able to enable APC for the CLI version of PHP easily.

apc.serializerstring

Used to configure APC to use a third party serializer.

apc.coredump_unmapbool

Enables APC handling of signals, such as SIGSEGV, that write core files when signaled. When these signals are received, APC will attempt to unmap the shared memory segment in order to exclude it from the core file. This setting may improve system stability when fatal signals are received and a large APC shared memory segment is configured.

Advertencia

This feature is potentially dangerous. Unmapping the shared memory segment in a fatal signal handler may cause undefined behaviour if a fatal error occurs.

Nota:

Although some kernels may provide a facility to ignore various types of shared memory when generating a core dump file, these implementations may also ignore important shared memory segments such as the Apache scoreboard.

apc.preload_pathstring

Optionally, set a path to the directory that APC will load cache data at startup.

apc.use_request_timebool

Use theSAPIrequest start time forTTL.



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

APC_ITER_ALL(integer)
APC_ITER_ATIME(integer)
APC_ITER_CTIME(integer)
APC_ITER_DEVICE(integer)
APC_ITER_DTIME(integer)
APC_ITER_FILENAME(integer)
APC_ITER_INODE(integer)
APC_ITER_KEY(integer)
APC_ITER_MD5(integer)
APC_ITER_MEM_SIZE(integer)
APC_ITER_MTIME(integer)
APC_ITER_NONE(integer)
APC_ITER_NUM_HITS(integer)
APC_ITER_REFCOUNT(integer)
APC_ITER_TTL(integer)
APC_ITER_TYPE(integer)
APC_ITER_VALUE(integer)
APC_LIST_ACTIVE(integer)
APC_LIST_DELETED(integer)



Funciones APCu


apcu_add

(PECL apcu >= 4.0.0)

apcu_addCache a new variable in the data store

Descripción

apcu_add(string$key,mixed$var,int$ttl= 0):bool
apcu_add(array$values,mixed$unused= NULL,int$ttl= 0):array

Caches a variable in the data store, only if it's not already stored.

Nota:Unlike many other mechanisms in PHP, variables stored usingapcu_add()will persist between requests (until the value is removed from the cache).

Parámetros

key

Store the variable using this name.keys are cache-unique, so attempting to useapcu_add()to store data with a key that already exists will not overwrite the existing data, and will instead returnfalse. (This is the only difference betweenapcu_add()andapcu_store().)

var

The variable to store

ttl

Time To Live; storevarin the cache forttlseconds. After thettlhas passed, the stored variable will be expunged from the cache (on the next request). If nottlis supplied (or if thettlis0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).

values

Names in key, variables in value.

Valores devueltos

Returns TRUE if something has effectively been added into the cache, FALSE otherwise. Second syntax returns array with error keys.

Ejemplos

Ejemplo #1 Aapcu_add()example

<?php
$bar
='BAR';
apcu_add('foo',$bar);
var_dump(apcu_fetch('foo'));
echo
"\n";
$bar='NEVER GETS SET';
apcu_add('foo',$bar);
var_dump(apcu_fetch('foo'));
echo
"\n";
?>

El resultado del ejemplo sería:

string(3) "BAR"
string(3) "BAR"

Ver también



apcu_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_infoRecupera la información almacenada en la memoria APCu

Descripción

apcu_cache_info(bool$limited=false):array

Recupera la información almacenada y los metadatos del almacén de datos de la APC.

Parámetros

limited

Si el parámetrolimitedestrue, el valor devuelto excluirá la lista individual de entradas de la memoria caché. Esto es útil cuando se intentan optimizar las llamadas para la recopilación de estadísticas.

Valores devueltos

Array de datos en caché (y metadatos) ofalseen caso de error

Nota:apcu_cache_info()hará una advertencia si no puede recuperar los datos de la caché del APC. Esto suele ocurrir cuando el APC no está activado.

Historial de cambios

VersiónDescripción
3.0.11El parámetrolimitedfué introducido.
3.0.16La opción "filehits" para el parámetrocache_typefué introducido.

Ejemplos

Ejemplo #1 Un ejemplo deapcu_cache_info()

<?php
print_r
(apcu_cache_info());
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [num_slots] => 2000
    [ttl] => 0
    [num_hits] => 9
    [num_misses] => 3
    [start_time] => 1123958803
    [cache_list] => Array
        (
            [0] => Array
                (
                    [filename] => /path/to/apcu_test.php
                    [device] => 29954
                    [inode] => 1130511
                    [type] => file
                    [num_hits] => 1
                    [mtime] => 1123960686
                    [creation_time] => 1123960696
                    [deletion_time] => 0
                    [access_time] => 1123962864
                    [ref_count] => 1
                    [mem_size] => 677
                )
            [1] => Array (...iterates for each cached file)
)

Ver también



apcu_cas

(PECL apcu >= 4.0.0)

apcu_casActualiza un valor antiguo con un nuevo valor

Descripción

apcu_cas(string$key,int$old,int$new):bool

apcu_cas()actualiza un valor entero ya existente si el parámetrooldcoincide el valor almacenado actualmente con el valor del parámetronew.

Parámetros

key

La clave del valor que se está actualizando.

old

El valor antiguo (el valor actualmente almacenado).

new

El nuevo valor al que actualizar.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deapcu_cas()

<?php
apcu_store
('foobar',2);
echo
'$foobar = 2',PHP_EOL;
echo
'$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar',1,2) ?'ok':'fail'),PHP_EOL;
echo
'$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar',2,1) ?'ok':'fail'),PHP_EOL;

echo
'$foobar = ',apcu_fetch('foobar'),PHP_EOL;

echo
'$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar',1,2) ?'ok':'fail'),PHP_EOL;

apcu_store('perfection','xyz');
echo
'$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection',2,1) ?'ok':'epic fail'),PHP_EOL;

echo
'$foobar = ',apcu_fetch('foobar'),PHP_EOL;
?>

El resultado del ejemplo sería algo similar a:

$foobar = 2
$foobar == 1 ? 2 : 1 = fail
$foobar == 2 ? 1 : 2 = ok
$foobar = 1
$f__bar == 1 ? 2 : 1 = fail
$perfection == 2 ? 1 : 2 = epic fail
$foobar = 1

Ver también



apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cacheLimpia el caché del APCu

Descripción

apcu_clear_cache():bool

Limpia el caché.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve siempretrue

Ver también



apcu_dec

(PECL apcu >= 4.0.0)

apcu_decDisminuir un número almacenado

Descripción

apcu_dec(
    string$key,
    int$step= 1,
    bool&$success= ?,
    int$ttl= 0
):int

Disminuye un valor entero almacenado.

Parámetros

key

La clave de el valor a ser disminuido.

step

El paso, o valor a disminuir.

success

Opcionalmente pasa el valor booleano en caso de éxito o en caso de error a esta variable referenciada.

ttl

TTL para usar si la operación inserta un nuevo valor (en lugar de disminuir uno existente).

Valores devueltos

Devuelve el valor actual del valor de las claves (key) en caso de éxito, ofalseen caso de error

Historial de cambios

VersiónDescripción
5.1.12El parámetrottlfué añadido.

Ejemplos

Ejemplo #1 Ejemplo deapcu_dec()

<?php
echo"Let's do something with success",PHP_EOL;

apcu_store('anumber',42);

echo
apcu_fetch('anumber'),PHP_EOL;

echo
apcu_dec('anumber'),PHP_EOL;
echo
apcu_dec('anumber',10),PHP_EOL;
echo
apcu_dec('anumber',10,$success),PHP_EOL;

var_dump($success);

echo
"Now, let's fail",PHP_EOL,PHP_EOL;

apcu_store('astring','foo');

$ret=apcu_dec('astring',1,$fail);

var_dump($ret);
var_dump($fail);
?>

El resultado del ejemplo sería algo similar a:

Let's do something with success
42
41
31
21
bool(true)
Now, let's fail

bool(false)
bool(false)

Ver también



apcu_delete

(PECL apcu >= 4.0.0)

apcu_deleteElimina una variable almacenada en caché

Descripción

apcu_delete(mixed$key):bool

Elimina una variable almacenada en caché.

Parámetros

key

Una clave (key) empleada para almacenar el valor como unstringpara una única clave, o como unarrayde strings para varias claves, o como unobjectAPCUIterator.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Un ejemplo deapcu_delete()

<?php
$bar
='BAR';
apcu_store('foo',$bar);
apcu_delete('foo');
// obviamente, esto no es útil de esta forma

// Alternativamente, borrar varias claves.
apcu_delete(['foo','bar','baz']);

// O utilizar un Iterator con una expresión regular.
apcu_delete(newAPCUIterator('#^myprefix_#'));
?>

Ver también



apcu_enabled

(PECL apcu >= 4.0.3)

apcu_enabledSi el APCu es utilizable en el entorno actual

Descripción

apcu_enabled():bool

Devuelve si el APCu es utilizable en el entorno actual.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetrueuando el APCu es utilizable en el entorno actual,falseen caso contrario.



apcu_entry

(PECL apcu >= 5.1.0)

apcu_entryAtomically fetch or generate a cache entry

Descripción

apcu_entry(string$key,callable$generator,int$ttl= 0):mixed

Atomically attempts to findkeyin the cache, if it cannot be foundgeneratoris called, passingkeyas the only argument. The return value of the call is then cached with the optionally specifiedttl, and returned.

Nota:When control entersapcu_entry()the lock for the cache is acquired exclusively, it is released when control leavesapcu_entry(): In effect, this turns the body ofgeneratorinto a critical section, disallowing two processes from executing the same code paths concurrently. In addition, it prohibits the concurrent execution of any other APCu functions, since they will acquire the same lock.

Advertencia

The only APCu function that can be called safely bygeneratorisapcu_entry().

Parámetros

key

Identity of cache entry

generator

A callable that acceptskeyas the only argument and returns the value to cache.

ttl

Time To Live; storevarin the cache forttlseconds. After thettlhas passed, the stored variable will be expunged from the cache (on the next request). If nottlis supplied (or if thettlis0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).

Valores devueltos

Returns the cached value

Ejemplos

Ejemplo #1 Anapcu_entry()example

<?php
$config
=apcu_entry("config", function($key) {
return [
"fruit"=>apcu_entry("config.fruit", function($key){
return [
"apples",
"pears"
];
}),
"people"=>apcu_entry("config.people", function($key){
return [
"bob",
"joe",
"niki"
];
})
];
});

var_dump($config);
?>

El resultado del ejemplo sería:

array(2) {
  ["fruit"]=>
  array(2) {
    [0]=>
    string(6) "apples"
    [1]=>
    string(5) "pears"
  }
  ["people"]=>
  array(3) {
    [0]=>
    string(3) "bob"
    [1]=>
    string(3) "joe"
    [2]=>
    string(4) "niki"
  }
}

Ver también



apcu_exists

(PECL apcu >= 4.0.0)

apcu_existsChecks if entry exists

Descripción

apcu_exists(mixed$keys):mixed

Checks if one or more APCu entries exist.

Parámetros

keys

Astring, or anarrayof strings, that contain keys.

Valores devueltos

Returnstrueif the key exists, otherwisefalseOr if anarraywas passed tokeys, then an array is returned that contains all existing keys, or an empty array if none exist.

Ejemplos

Ejemplo #1apcu_exists()example

<?php
$fruit
='apple';
$veggie='carrot';

apcu_store('foo',$fruit);
apcu_store('bar',$veggie);

if (
apcu_exists('foo')) {
echo
"Foo exists: ";
echo
apcu_fetch('foo');
} else {
echo
"Foo does not exist";
}

echo
PHP_EOL;
if (
apcu_exists('baz')) {
echo
"Baz exists.";
} else {
echo
"Baz does not exist";
}

echo
PHP_EOL;

$ret=apcu_exists(array('foo','donotexist','bar'));
var_dump($ret);

?>

El resultado del ejemplo sería algo similar a:

Foo exists: apple
Baz does not exist
array(2) {
  ["foo"]=>
  bool(true)
  ["bar"]=>
  bool(true)
}

Ver también



apcu_fetch

(PECL apcu >= 4.0.0)

apcu_fetchFetch a stored variable from the cache

Descripción

apcu_fetch(mixed$key,bool&$success= ?):mixed

Fetches an entry from the cache.

Parámetros

key

Thekeyused to store the value (withapcu_store()). If an array is passed then each element is fetched and returned.

success

Set totruein success andfalsein failure.

Valores devueltos

The stored variable or array of variables on success;falseon failure

Historial de cambios

VersiónDescripción
PECL apcu 3.0.17Thesuccessparameter was added.

Ejemplos

Ejemplo #1 Aapcu_fetch()example

<?php
$bar
='BAR';
apcu_store('foo',$bar);
var_dump(apcu_fetch('foo'));
?>

El resultado del ejemplo sería:

string(3) "BAR"

Ver también



apcu_inc

(PECL apcu >= 4.0.0)

apcu_incIncrease a stored number

Descripción

apcu_inc(
    string$key,
    int$step= 1,
    bool&$success= ?,
    int$ttl= 0
):int|false

Increases a stored number.

Parámetros

key

The key of the value being increased.

step

The step, or value to increase.

success

Optionally pass the success or fail boolean value to this referenced variable.

ttl

TTL to use if the operation inserts a new value (rather than incrementing an existing one).

Valores devueltos

Returns the current value ofkey's value on success, ofalseen caso de error

Ejemplos

Ejemplo #1apcu_inc()example

<?php
echo"Let's do something with success",PHP_EOL;

apcu_store('anumber',42);

echo
apcu_fetch('anumber'),PHP_EOL;

echo
apcu_inc('anumber'),PHP_EOL;
echo
apcu_inc('anumber',10),PHP_EOL;
echo
apcu_inc('anumber',10,$success),PHP_EOL;

var_dump($success);

echo
"Now, let's fail",PHP_EOL,PHP_EOL;

apcu_store('astring','foo');

$ret=apcu_inc('astring',1,$fail);

var_dump($ret);
var_dump($fail);
?>

El resultado del ejemplo sería algo similar a:

Let's do something with success
42
43
53
63
bool(true)
Now, let's fail

bool(false)
bool(false)

Ver también



apcu_key_info

(No version information available, might only be in Git)

apcu_key_infoGet detailed information about the cache key

Descripción

apcu_key_info(string$key):?array

Get detailed information about the cache key

Parámetros

key

Get detailed information about the cache key

Valores devueltos

An array containing the detailed information about the cache key, ornullif the key does not exist.

Ejemplos

Ejemplo #1 Aapcu_key_info()example

<?php
apcu_add
('a','b');
var_dump(apcu_key_info('a'));
?>

El resultado del ejemplo sería:

array(7) {
  ["hits"]=>
  int(0)
  ["access_time"]=>
  int(1606701783)
  ["mtime"]=>
  int(1606701783)
  ["creation_time"]=>
  int(1606701783)
  ["deletion_time"]=>
  int(0)
  ["ttl"]=>
  int(0)
  ["refs"]=>
  int(0)
}

Ver también



apcu_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_infoRetrieves APCu Shared Memory Allocation information

Descripción

apcu_sma_info(bool$limited=false):array|false

Retrieves APCu Shared Memory Allocation information.

Parámetros

limited

When set tofalse(default)apcu_sma_info()will return a detailed information about each segment.

Valores devueltos

Array of Shared Memory Allocation data;falseon failure.

Ejemplos

Ejemplo #1 Aapcu_sma_info()example

<?php
print_r
(apcu_sma_info());
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [num_seg] => 1
    [seg_size] => 31457280
    [avail_mem] => 31448408
    [block_lists] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [size] => 31448408
                            [offset] => 8864
                        )

                )

        )

)



apcu_store

(PECL apcu >= 4.0.0)

apcu_storeCache a variable in the data store

Descripción

apcu_store(string$key,mixed$var,int$ttl= 0):bool
apcu_store(array$values,mixed$unused= NULL,int$ttl= 0):array

Cache a variable in the data store.

Nota:Unlike many other mechanisms in PHP, variables stored usingapcu_store()will persist between requests (until the value is removed from the cache).

Parámetros

key

Store the variable using this name.keys are cache-unique, so storing a second value with the samekeywill overwrite the original value.

var

The variable to store

ttl

Time To Live; storevarin the cache forttlseconds. After thettlhas passed, the stored variable will be expunged from the cache (on the next request). If nottlis supplied (or if thettlis0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).

values

Names in key, variables in value.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error. Second syntax returns array with error keys.

Ejemplos

Ejemplo #1 Aapcu_store()example

<?php
$bar
='BAR';
apcu_store('foo',$bar);
var_dump(apcu_fetch('foo'));
?>

El resultado del ejemplo sería:

string(3) "BAR"

Ver también


Tabla de contenidos



La clase APCUIterator

(PECL apcu >= 5.0.0)

Introducción

La claseAPCUIteratorhace más fácil iterar sobre grandes cachés de APCu. Esto es útil ya que permite iterar sobre grandes cachés en pasos, al mismo tiempo que captura un número definido de entradas por instancia de bloqueo, por lo que libera los bloqueos de caché para otras actividades en lugar de mantener todo el caché para obtener 100 entradas (el valor por defecto). Además, utilizar comparación por expresiones regulares es más eficiente ya que se ha movido al nivel de C.

Sinopsis de la Clase

classAPCUIteratorimplementsIterator{
/* Métodos */
public__construct(
    mixed$search=null,
    int$format= APC_ITER_ALL,
    int$chunk_size= 100,
    int$list= APC_LIST_ACTIVE
)
publiccurrent():mixed
publicgetTotalCount():int
publicgetTotalHits():int
publicgetTotalSize():int
publickey():string
publicnext():bool
publicrewind():void
publicvalid():bool
}

APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__constructConstruye un objeto iterador APCUIterator

Descripción

publicAPCUIterator::__construct(
    mixed$search=null,
    int$format= APC_ITER_ALL,
    int$chunk_size= 100,
    int$list= APC_LIST_ACTIVE
)

Construye unAPCUIteratorobject.

Parámetros

search

Una expresión regular delPCREque coincide con los nombres clave de la APCu, ya sea comostringpara una sola expresión regular, o como unarrayde expresiones regular. O, opcionalmente pasar ennullpara saltarse la búsqueda.

format

El formato deseado, tal como está configurado con una o más de las constantesAPC_ITER_*.

chunk_size

El tamaño del fragmento. Debe ser un valor mayor que 0. El valor por defecto es 100.

list

El tipo de lista. O bien pasar enAPC_LIST_ACTIVEoAPC_LIST_DELETED.

Valores devueltos

UnAPCUIteratorobjecten caso de éxito, onullen caso de error.

Ejemplos

Ejemplo #1 Un ejemplo deAPCUIterator::__construct()

<?php
foreach (newAPCUIterator('/^counter\./') as$counter) {
echo
"$counter[key]:$counter[value]\n";
apc_dec($counter['key'],$counter['value']);
}
?>

Ver también



APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::currentObtener el elemento actual

Descripción

publicAPCUIterator::current():mixed

Obtiene el elemento actual de la pilaAPCUIterator.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el elemento actual en caso de éxito, ofalsesi no hay más elementos o no existen, o en caso de error.

Ver también



APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCountObtiene el conteo total

Descripción

publicAPCUIterator::getTotalCount():int

Obtener el conteo total.

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

El conteo total.

Ver también



APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHitsObtener resultados totales de la memoria caché

Descripción

publicAPCUIterator::getTotalHits():int

Obtiene el número total de visitas a la memoria caché.

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

El número de visitas en caso de éxito, ofalseen caso de error.

Ver también



APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSizeObtiene el tamaño total del caché

Descripción

publicAPCUIterator::getTotalSize():int

Obtiene el tamaño total del caché.

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

El tamaño total del caché.

Ver también



APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::keyObtiene la clave del iterador

Descripción

publicAPCUIterator::key():string

Obtiene la clave del iterador actual.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la clave en caso de éxito, ofalseen caso de error.

Ver también



APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::nextMueve el puntero al siguiente elemento

Descripción

publicAPCUIterator::next():bool

Mueve el puntero del iterador al siguiente elemento.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewindRebobina el iterador

Descripción

publicAPCUIterator::rewind():void

Rebobina el iterador hasta el primer elemento.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.

Ver también



APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::validComprueba si la posición actual es válida

Descripción

publicAPCUIterator::valid():bool

Comprueba si la posición actual del iterador es válida.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetruesi la posición actual del iterador es válida, en caso contrariofalse.

Ver también


Tabla de contenidos




Componere


Introducción

Componere(latin, English: compose)se dirige a los entornos de producción y proporciona una API para composición de las clases, parches y moldeado.

Composición:

Componere\Definitionse utiliza para definir (o redefinir) una clase en tiempo de ejecución; La clase puede entonces registrarse, y en caso de redefinición reemplaza a la clase original durante todo el tiempo que la claseComponere\Definitionexista.

publicComponere\Definition::__construct(string$name,string$parent)
publicComponere\Definition::__construct(string$name,array$interfaces)
publicComponere\Definition::__construct(string$name,string$parent,array$interfaces)

Parcheado:

Componere\Patchse utiliza para cambiar la clase de una instancia específica de un objeto en tiempo de ejecución; Tras su aplicación, el parche permanecerá aplicado durante todo el tiempo que la claseComponere\Patchexista, y puede ser revertido explícitamente.

publicComponere\Patch::__construct(object$instance)
publicComponere\Patch::__construct(object$instance,array$interfaces)

Moldeado:

Componere\Las funciones de moldeado pueden moldear entre tipos compatibles definidos por el usuario; Donde compatible significaTypees sub o super al tipo deobject.

Componere\cast(Type$type,$object):Type
Componere\cast_by_ref(Type$type,$object):Type



Instalación/Configuración

Tabla de contenidos


Requerimientos

Se requiere Reflection



Instalación

La fuente de Componere y las liberaciones están disponibles en» github




La clase Componere\Abstract\Definition

(Componere 2 >= 2.1.0)

Introducción

Esta abstracta final representa una entrada de clase, y no debe ser usado por el programador.

Sinopsis de la Clase

finalabstractclassComponere\Abstract\Definition{
/* Métodos */
publicaddInterface(string$interface):Definition
publicaddMethod(string$name,\Componere\Method$method):Definition
publicaddTrait(string$trait):Definition
publicgetReflector():\ReflectionClass
}

Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterfaceAñadir Interface

Descripción

publicComponere\Abstract\Definition::addInterface(string$interface):Definition

Implementará la interface dada en la definición actual

Parámetros

interface

El nombre de una interface insensible a las mayúsculas y minúsculas

Valores devueltos

La definición actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsiDefinitionse registró



Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethodAñadir método

Descripción

publicComponere\Abstract\Definition::addMethod(string$name,\Componere\Method$method):Definition

Creará o anulará un método en la definición actual.

Parámetros

name

El nombre del método insensible a las mayúsculas y minúsculas

method

\Componere\Methodque no se haya añadido previamente a otraDefinition

Valores devueltos

La Definition actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsiDefinitionse registró

Advertencia

LanzaráRuntimeExceptionsi el método se añadió a otra definición



Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTraitAñadir rasgo

Descripción

publicComponere\Abstract\Definition::addTrait(string$trait):Definition

Usará el rasgo dado para la definición actual

Parámetros

trait

El nombre del rasgo insensible a las mayúsculas y minúsculas

Valores devueltos

La definición actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsiDefinitionse registró



Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflectorReflection

Descripción

publicComponere\Abstract\Definition::getReflector():\ReflectionClass

Creará o devolverá una clase Reflection

Valores devueltos

Una clase Reflection para la definición actual (en caché)


Tabla de contenidos



La clase Componere\Definition

(Componere 2 >= 2.1.0)

Introducción

La clase Definition permite al programador construir y registrar un tipo en tiempo de ejecución.

En caso de que una Definition reemplace una clase existente, la clase existente será restaurada cuando la Definition sea destruida.

Sinopsis de la Clase

finalclassComponere\DefinitionextendsComponere\Abstract\Definition{
/* Constructores */
public__construct(string$name)
public__construct(string$name,string$parent)
public__construct(string$name,array$interfaces)
public__construct(string$name,string$parent,array$interfaces)
/* Métodos */
publicaddConstant(string$name,\Componere\Value$value):Definition
publicaddProperty(string$name,\Componere\Value$value):Definition
publicregister():void
publicisRegistered():bool
publicgetClosure(string$name):\Closure
publicgetClosures():array
/* Métodos heredados */
publicComponere\Abstract\Definition::addInterface(string$interface):Definition
publicComponere\Abstract\Definition::addMethod(string$name,\Componere\Method$method):Definition
publicComponere\Abstract\Definition::addTrait(string$trait):Definition
}

Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__constructConstructor Definition

Descripción

publicComponere\Definition::__construct(string$name)
publicComponere\Definition::__construct(string$name,string$parent)
publicComponere\Definition::__construct(string$name,array$interfaces)
publicComponere\Definition::__construct(string$name,string$parent,array$interfaces)

Parámetros

name

Un nombre de clase insensible a las mayúsculas y minúsculas

parent

Un nombre de clase insensible a las mayúsculas y minúsculas

interfaces

Un array de nombres de clase insensibles a las mayúsculas y minúsculas

Exceptions

Advertencia

LanzaráInvalidArgumentExceptionsi se intenta reemplazar una clase interna

Advertencia

LanzaráInvalidArgumentExceptionsi se intenta sustituir una interface

Advertencia

LanzaráInvalidArgumentExceptionsi se intenta reemplazar un rasgo

Advertencia

LanzaráRuntimeExceptionsi una clase eninterfacesno se puede encontrar

Advertencia

LanzaráRuntimeExceptionsi una clase eninterfacesno es una interface



Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstantAñade constante

Descripción

publicComponere\Definition::addConstant(string$name,\Componere\Value$value):Definition

Declarará una constante de clase en la definición actual

Parámetros

name

El nombre de la constante que distingue entre mayúsculas y minúsculas

value

El valor de la constante, no debe ser indefinido o estático

Valores devueltos

La definición actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsiDefinitionfué registrado

Advertencia

LanzaráRuntimeExceptionsinameya está declarada como una constante

Advertencia

LanzaráRuntimeExceptionsivaluees estática

Advertencia

LanzaráRuntimeExceptionsivalueno está definida



Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addPropertyAñade propiedad

Descripción

publicComponere\Definition::addProperty(string$name,\Componere\Value$value):Definition

Declarará una propiedad de clase sobre la definición actual

Parámetros

name

El nombre de la propiedad distingue mayúsculas y minúsculas

value

El valor por omisión de la propiedad

Valores devueltos

La definición actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsiDefinitionse registró

Advertencia

LanzaráRuntimeExceptionsinameya está declarada como una propiedad



Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::registerRegistro

Descripción

publicComponere\Definition::register():void

Registrará la Definition actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsiDefinitionfué registrada



Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegisteredDetección del estado

Descripción

publicComponere\Definition::isRegistered():bool

Deberá detectar el estado de registro de Definition

Valores devueltos

Devolverá true si Definition está registrada



Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosureObtener Cierre

Descripción

publicComponere\Definition::getClosure(string$name):\Closure

Devolverá un cierre para el método especificado por el nombre

Parámetros

name

El nombre del método insensible a las mayúsculas y minúsculas

Valores devueltos

Un cierre vinculado al alcance correcto

Exceptions

Advertencia

LanzaráRuntimeExceptionsiDefinitionse registró

Advertencia

LanzaráRuntimeExceptionsinameno se pudo encontrar



Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosuresObtener Cierres

Descripción

publicComponere\Definition::getClosures():array

Devolverá un array de cierres

Valores devueltos

Devolverá todos los métodos como un array de objetos de cierre vinculados al alcance correcto

Exceptions

Advertencia

LanzaráRuntimeExceptionsiDefinitionse registró


Tabla de contenidos



La clase Componere\Patch

(Componere 2 >= 2.1.0)

Introducción

La clase Patch permite al programador cambiar el tipo de una instancia en tiempo de ejecución sin registrar una nueva Definition

Cuando se destruye un parche se revierte, de modo que los casos que fueron parcheados durante la vida del Parche son restaurados a su tipo formal.

Sinopsis de la Clase

finalclassComponere\PatchextendsComponere\Abstract\Definition{
/* Constructors */
public__construct(object$instance)
public__construct(object$instance,array$interfaces)
/* Métodos */
publicapply():void
publicrevert():void
publicisApplied():bool
publicderive(object$instance):Patch
publicgetClosure(string$name):\Closure
publicgetClosures():array
/* Métodos heredados */
publicComponere\Abstract\Definition::addInterface(string$interface):Definition
publicComponere\Abstract\Definition::addMethod(string$name,\Componere\Method$method):Definition
publicComponere\Abstract\Definition::addTrait(string$trait):Definition
}

Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__constructConstructor Patch

Descripción

publicComponere\Patch::__construct(object$instance)
publicComponere\Patch::__construct(object$instance,array$interfaces)

Parámetros

instance

El objetivo de este Patch

interfaces

Un array de nombres de clase insensibles a las mayúsculas y minúsculas

Exceptions

Advertencia

LanzaráRuntimeExceptionsi una clase eninterfacesno se puede encontrar

Advertencia

LanzaráRuntimeExceptionsi una clase eninterfacesno es una interface



Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::applyAplicación

Descripción

publicComponere\Patch::apply():void

Aplicará el parche actual



Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revertReversión

Descripción

publicComponere\Patch::revert():void

Revertirá el parche actual



Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isAppliedDetección del estado

Descripción

publicComponere\Patch::isApplied():bool


Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::deriveDerivación del parche

Descripción

publicComponere\Patch::derive(object$instance):Patch

Derivará unPatch(parche) para lainstance(instancia) dada

Parámetros

instance

El objetivo del Parche derivado

Valores devueltos

Patch(parche) para lainstance(instancia) derivada delPatch(parche) actual

Exceptions

Advertencia

LanzaráInvalidArgumentExceptionsiinstanceno es compatible



Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosureObtener Cierre

Descripción

publicComponere\Patch::getClosure(string$name):\Closure

Devolverá un cierre para el método especificado por el nombre

Parámetros

name

El nombre del método insensible a las mayúsculas y minúsculas

Valores devueltos

Un cierre vinculado al ámbito y objeto correctos

Exceptions

Advertencia

LanzaráRuntimeExceptionsinameno se pudo encontrar



Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosuresObtener Cierres

Descripción

publicComponere\Patch::getClosures():array

Devolverá un array de Cierres

Valores devueltos

Devolverá todos los métodos como un array de objetos de cierre unidos al ámbito y objeto correctos


Tabla de contenidos



La clase Componere\Method

(Componere 2 >= 2.1.0)

Introducción

Un método representa una función con banderas de accesibilidad modificables

Sinopsis de la Clase

finalclassComponere\Method{
/* Constructor */
public__construct(\Closure$closure)
/* Métodos */
publicsetPrivate():Method
publicsetProtected():Method
publicsetStatic():Method
publicgetReflector():\ReflectionMethod
}

Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__constructConstructor Method

Descripción

publicComponere\Method::__construct(\Closure$closure)

Parámetros

closure



Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivateModificación de la accesibilidad

Descripción

publicComponere\Method::setPrivate():Method

Valores devueltos

El método actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsi el nivel de acceso fue establecido previamente



Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtectedModificación de la accesibilidad

Descripción

publicComponere\Method::setProtected():Method

Valores devueltos

El método actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsi el nivel de acceso fue establecido previamente



Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStaticModificación de la accesibilidad

Descripción

publicComponere\Method::setStatic():Method

Valores devueltos

El método actual



Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflectorReflection

Descripción

publicComponere\Method::getReflector():\ReflectionMethod

Creará o devolverá un Método de Reflection

Valores devueltos

Un método de Reflection para el método actual (en caché)


Tabla de contenidos



La clase Componere\Value

(Componere 2 >= 2.1.0)

Introducción

Una clase Value representa una variable PHP de todos los tipos, incluyendo las indefinidas

Sinopsis de la Clase

finalclassComponere\Value{
/* Constructor */
public__construct($default= ?)
/* Métodos */
publicsetPrivate():Value
publicsetProtected():Value
publicsetStatic():Value
publicisPrivate():bool
publicisProtected():bool
publicisStatic():bool
publichasDefault():bool
}

Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__constructConstructor Value

Descripción

publicComponere\Value::__construct($default= ?)

Parámetros

default

Exceptions

Advertencia

LanzaráInvalidArgumentExceptionsidefaultno tiene un valor adecuado



Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivateModificación de la accesibilidad

Descripción

publicComponere\Value::setPrivate():Value

Valores devueltos

El valor actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsi el nivel de acceso fue establecido previamente



Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtectedModificación de la accesibilidad

Descripción

publicComponere\Value::setProtected():Value

Valores devueltos

El valor actual

Exceptions

Advertencia

LanzaráRuntimeExceptionsi el nivel de acceso fue establecido previamente



Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStaticModificación de la accesibilidad

Descripción

publicComponere\Value::setStatic():Value

Valores devueltos

El valor actual



Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivateDetección de accesibilidad

Descripción

publicComponere\Value::isPrivate():bool



Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtectedDetección de accesibilidad

Descripción

publicComponere\Value::isProtected():bool



Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStaticDetección de accesibilidad

Descripción

publicComponere\Value::isStatic():bool



Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefaultInteracción de Value

Descripción

publicComponere\Value::hasDefault():bool


Tabla de contenidos



Funciones Componere


Componere\cast

(Componere 2 >= 2.1.2)

Componere\castMoldeado

Descripción

Componere\cast(Type$type,$object):Type

Parámetros

type

Un tipo definido por el usuario

object

Un objeto con un tipo definido por el usuario compatible conType

Valores devueltos

Unobjectde tipoType, moldeado deobject

Exceptions

Advertencia

LanzaráInvalidArgumentExceptionsi el tipo deobjectes o se deriva de una clase interna

Advertencia

LanzaráInvalidArgumentExceptionsiTypees una interface

Advertencia

LanzaráInvalidArgumentExceptionsiTypees un rasgo

Advertencia

LanzaráInvalidArgumentExceptionsiTypees una abstracta

Advertencia

LanzaráInvalidArgumentExceptionsiTypeno es compatible con el tipo deobject



Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_refMoldeado

Descripción

Componere\cast_by_ref(Type$type,$object):Type

Parámetros

type

Un tipo definido por el usuario

object

Un objeto con un tipo definido por el usuario compatible conType

Valores devueltos

Unobjectde tipoType, moldeado deobject, donde los miembros son referencias a miembros deobject

Exceptions

Advertencia

LanzaráInvalidArgumentExceptionsi el tipo deobjectes o se deriva de una clase interna

Advertencia

LanzaráInvalidArgumentExceptionsiTypees una interface

Advertencia

LanzaráInvalidArgumentExceptionsiTypees un rasgo

Advertencia

LanzaráInvalidArgumentExceptionsiTypees una abstracta

Advertencia

LanzaráInvalidArgumentExceptionsiTypeno es compatible con el tipo deobject

Ver también


Tabla de contenidos




Manejo y registro de errores


Introducción

Estas funciones se ocupan del manejo y registro de errores. Le permiten definir sus propias reglas de manejo de errores, así como modificar la manera en que los errores pueden ser registrados. Esto le permite cambiar y mejorar la notificación de errores para acomodarla a sus necesidades.

Con las funciones de registro se pueden enviar mensajes directamente a otras máquinas, a un e-mail (¡o un e-mail a un busca!), al registro del sistema, etc., por lo que puede registrar y monitorizar selectivamente las partes más importantes de sus aplicaciones y sitios web.

Las funciones de notificación de errores le permiten personalizar qué niveles y tipos de errores se dan, abarcando desde simples avisos hasta funciones personalizadas devueltas al originarse un error.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

No se requiere de ninguna instalación para utilizar estas funciones; forman parte del núcleo de PHP.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Opciones de configuración de errores y registro
NombrePor defectoCambiableHistorial de cambios
error_reportingNULLPHP_INI_ALL 
display_errors"1"PHP_INI_ALL 
display_startup_errors"0"PHP_INI_ALL 
log_errors"0"PHP_INI_ALL 
log_errors_max_len"1024"PHP_INI_ALLDisponible a partir de PHP 4.3.0.
ignore_repeated_errors"0"PHP_INI_ALLDisponible a partir de PHP 4.3.0.
ignore_repeated_source"0"PHP_INI_ALLDisponible a partir de PHP 4.3.0.
report_memleaks"1"PHP_INI_ALLDisponible a partir de PHP 4.3.0.
track_errors"0"PHP_INI_ALL 
html_errors"1"PHP_INI_ALLPHP_INI_SYSTEM en PHP <= 4.2.3.
xmlrpc_errors"0"PHP_INI_SYSTEMDisponible a partir de PHP 4.1.0.
xmlrpc_error_number"0"PHP_INI_ALLDisponible a partir de PHP 4.1.0.
docref_root""PHP_INI_ALLDisponible a partir de PHP 4.3.0.
docref_ext""PHP_INI_ALLDisponible a partir de PHP 4.3.2.
error_prepend_stringNULLPHP_INI_ALL 
error_append_stringNULLPHP_INI_ALL 
error_logNULLPHP_INI_ALL 
error_log_mode0o644PHP_INI_ALLDisponible a partir de PHP 8.2.0
syslog.facility"LOG_USER"PHP_INI_SYSTEMDisponible a partir de PHP 7.3.0.
syslog.filter"no-ctrl"PHP_INI_ALLDisponible a partir de PHP 7.3.0.
syslog.ident"php"PHP_INI_SYSTEMDisponible a partir de PHP 7.3.0.
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

error_reportinginteger

Establece el nivel de notificación de errores. El parámetro es o bien un valor de tipo integer que representa un campo de bits, o bien constantes con nombre. Los niveles de error_reporting y las constantes están descritos enConstantes predefinidas, y enphp.ini. Para establecerlo en tiempo de ejecución, se ha de usar la funciónerror_reporting(). Vése también la directivadisplay_errors.

En PHP 5.3 o posterior, el valor predeterminado esE_ALL& ~E_NOTICE& ~E_STRICT& ~E_DEPRECATED. Este ajuste no muestra los niveles de errorE_NOTICE,E_STRICTyE_DEPRECATED. Quizás quiera mostrarlos durante el desarrollo. Antes de PHP 5.3.0, el valor predeterminado esE_ALL& ~E_NOTICE& ~E_STRICT. en PHP, el valor predeterminado esE_ALL& ~E_NOTICE.

Nota:

La habilitación deE_NOTICEdurante el desarrollo tiene algunos beneficios. Para las depuración: los mensajes NOTICE avisarán de posibles errores en el código. Por ejemplo, se advierte del uso de valores no asignados. Es extremadamente útil para encontrar errartas y ahorrar tiempo en la depuración. Los mensajes NOTICE avisarán de un estilo malo. Por ejemplo,$arr[item]es mejor que sea escrito como$arr['item']ya que PHP intenta tratar"item"como una constante. Si no es una constante, PHP asume que es un índice de string del array.

Nota:

En PHP 5 está disponible el nuevo nivel de errorE_STRICT. Antes de PHP 5.4.0,E_STRICTno estaba incluido dentro deE_ALL, por lo que se teniía de habilitar explícitamente este tipo de nivel de error en PHP < 5.4.0. La habilitación deE_STRICTdurante el desarrollo tiene algunos beneficios. Los mensajes STRICT proporcionan sugerencias que pueden ayudar a asegurarse de la mejor interoperabilidad y la compatibilidad hacia delante del código. Estos mensajes pueden incluir cosas como llamar a métodos no estáticos de forma estática, definir propiedades en una definición de clase compatible mientras se definió en un trait usado, y antes de PHP 5.3, algunas características obsoletas emitirían erroresE_STRICTcomo asignar objetos por referencias durante la instanciación.

Nota:Constantes de PHP fuera de PHP

El uso de constantes de PHP fuera de PHP, como enhttpd.conf, no tiene un propósito útil, por lo que, en tales casos, se requerirán los valores de tipointeger. Y ya que se añadirán más niveles de error en el futuro, el valor máximo (paraE_ALL) cambiará igualmente. Por lo que, en lugar deE_ALLse ha de considerar el uso de un valor grande para cubrir todos los campos de bits desde la actualidad hasta bien entrado en el futuro, un valor numérico como2147483647(incluye todos los errores, no sóloE_ALL).

display_errorsstring

Determina si los errores deberían ser impresos en pantalla como parte de la salida o si deberían ocultarse al usuario.

El valor"stderr"envía los errores astderren vez de astdout. Este valor está disponible a partir de PHP 5.2.4. En versiones anteriores esta directiva era de tipoboolean.

Nota:

Ésta es una característica para ayudar al desarrollo y nunca debería usarse en sistemas de producción (p.ej. en sistemas conectados a internet).

Nota:

Aunque display_errors puede ser establecido en tiempo de ejecución (conini_set()), no tendrá ningún efecto si el script tiene errores fatales. Esto es debido a que la acción deseada en tiempo de ejecución no se ejecuta.

display_startup_errorsboolean

Incluso cuando display_errors está activado, los errores que ocurren durante la secuencia de arranque de PHP no se muestran. Se recomienda encarecidamente mantener desactivado display_startup_errors, excepto para la depuración.

log_errorsboolean

Indica si los mensajes de error del script deberían de registrarse en el registro del servidor o enerror_log. Esta opción es, por lo tanto, específica para servidores.

Nota:

Se aconseja encarecidamente usar el registro de errores en lugar de mostrar los errores en sitios web de producción.

log_errors_max_leninteger

Establece la longitud máxima de log_errors en bytes. Enerror_logse añade información acerca del origen. El valor predeterminado es 1024, y 0 permite no aplicar ninguna longitud máxima en absoluto. Esta longitud se aplica a los errores registrados, a los errores mostrados y también a$php_errormsg, pero no a las funciones llamadas explícitamente tal comeerror_log().

Cuando se usa uninteger, el valor del mismo es medido en bytes. También se puede usar la notación reducida, tal como se describe enesta FAQ.
ignore_repeated_errorsboolean

No registra mensajes repetidos. Los mensajes repetidos deben ocurrir en la misma línea del mismo fichero a menos queignore_repeated_sourceesté establecido a true.

ignore_repeated_sourceboolean

Ignora el origen del mensaje cuando se ignoran mensajes repetidos. Cuando este ajuste está activado (On) no se registrarán errores con mensajes repetidos de diferentes ficheros o líneas del código fuente.

report_memleaksboolean

Si este parámetro está activado (On), que es lo predeterminado, mostrará un informe de pérdidas de memoria detectado por el gestor de memoria Zend. Este informe será enviado a stderr en las plataformas Posix. En Windows, será enviado al depurador usando OutputDebugString(), y podrá ser visto con herramientas como» DbgView. Este parámetro solo tiene efecto en una versión de depuración, y si error_reporting incluyeE_WARNINGen la lista permitida.

track_errorsboolean

Si está habilitado, el último mensaje de error siempre estará presente en la variable$php_errormsg.

html_errorsboolean

Si se habilita, los mensajes de error incluirán etiquetas HTML. El formato para los errores HTML produce mensajes clicables que dirigen al usuario a una página que describe el error o función que causó el error. Estas referencias se ven afectadas pordocref_rootydocref_ext.

Si se inhabilita, el mensaje de error será solamente texto plano.

xmlrpc_errorsboolean

Si se habilita, se desactiva el reporte de errores normal y se formatean los errores como mensajes de error XML-RPC.

xmlrpc_error_numberinteger

Usado como el valor del elemento faultCode de XML-RPC.

docref_rootstring

El nuevo formato de error contiene una referencia a una página que describe el error o a la función que causa el error. En caso de páginas de manual, se puede descargar el manual en su idioma y establecer esta directiva ini al URL de su copia local. Si a su copia local del manual se puede llegar mediante"/manual/"puede usar simplementedocref_root=/manual/. Además tiene que establecer docref_ext para que coincida con las extensiones de fichero de su copiadocref_ext=.html. Es posible usar referencias externas. Por ejemplo, se puede usardocref_root=http://manual/en/odocref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"

La mayoría de las veces será necesario que el valor de docref_root termine con una barra"/". Sin embargo, veáse el segundo ejemplo de antes, el cuál ni la tiene ni la necesita.

Nota:

Esta es una característica para ayudar al desarrollo, ya que hace más fácil buscar una descripción de una función. Sin embargo, nunca debería usarse en sistemas de producción (p.ej. en sistemas conectados a internet).

docref_extstring

Véasedocref_root.

Nota:

El valor de docref_ext debe comenzar con un punto".".

error_prepend_stringstring

String a imprimir antes de un mensaje de error.

error_append_stringstring

String a imprimir después de un mensaje de error.

error_logstring

Nombre del fichero donde los errores del script deberían ser registrados. El fichero debería ser modificable por el usuario del servidor web. Si se usa el valor especialsyslog, los errores son enviados en su lugar al registro del sistema. En Unix, esto quiere decir syslog(3) y en Windows quiere decir el registro de sucesos. Véase también:syslog(). Si esta directiva no está establecida, los errores se enviarán al registro de error de la SAPI. Por ejemplo, un registro de error en Apache ostderren CLI. Véase tambiénerror_log().

error_log_modeint

File mode for the file described set inerror_log.

syslog.facilitystring

Especifica el tipo de programa que está registrando el mensaje. Solamente efectivo sierror_logse establece a "syslog".

syslog.filterstring

Especifica el tipo de filtro a aplicar a los mensajes registrados. Los caracteres pertimitos se pasan sin modificar; los demás se escriben en su representación hexadecimal prefijados con\x. Existen tres tipos de filtro permitidos:

  • all– todos los caracteres
  • no-ctrl– todos los caracteres excepto los de control
  • ascii– todos los caracteres ASCII imprimibles yNL
Solamente efectivo sierror_logse establece a "syslog".

syslog.identstring

Especifica la cadena de sangrado que antecede a todo mensaje. Solamente efectivo sierror_logse establece a "syslog".



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Estas constantes están disponibles siempre ya que forman parte del núcleo de PHP.

Nota:Se pueden usar estos nombres de constantes enphp.inipero no fuera de PHP, como enhttpd.conf, donde se deberían usar en su lugar valores de máscara de bits.

Errores y Registro
ValorConstanteDescripciónNota
1E_ERROR(integer)Errores Fatales en tiempo de ejecución. Éstos indican errores que no se pueden recuperar, tales como un problema de asignación de memoria. La ejecución del script se interrumpe. 
2E_WARNING(integer)Advertencias en tiempo de ejecución (errores no fatales). La ejecución del script no se interrumpe. 
4E_PARSE(integer)Errores de análisis en tiempo de compilación. Los errores de análisis deberían ser generados únicamente por el analizador. 
8E_NOTICE(integer)Avisos en tiempo de ejecución. Indican que el script encontró algo que podría señalar un error, pero que también podría ocurrir en el curso normal al ejecutar un script. 
16E_CORE_ERROR(integer)Errores fatales que ocurren durante el arranque incial de PHP. Son como unE_ERROR, excepto que son generados por el núcleo de PHP. 
32E_CORE_WARNING(integer)Advertencias (errores no fatales) que ocurren durante el arranque inicial de PHP. Son como unE_WARNING, excepto que son generados por el núcleo de PHP. 
64E_COMPILE_ERROR(integer)Errores fatales en tiempo de compilación. Son como unE_ERROR, excepto que son generados por Motor de Script Zend. 
128E_COMPILE_WARNING(integer)Advertencias en tiempo de compilación (errores no fatales). Son como unE_WARNING, excepto que son generados por Motor de Script Zend. 
256E_USER_ERROR(integer)Mensaje de error generado por el usuario. Es como unE_ERROR, excepto que es generado por código de PHP mediante el uso de la función de PHPtrigger_error(). 
512E_USER_WARNING(integer)Mensaje de advertencia generado por el usuario. Es como unE_WARNING, excepto que es generado por código de PHP mediante el uso de la función de PHPtrigger_error(). 
1024E_USER_NOTICE(integer)Mensaje de aviso generado por el usuario. Es como unE_NOTICE, excepto que es generado por código de PHP mediante el uso de la función de PHPtrigger_error(). 
2048E_STRICT(integer)Habilítelo para que PHP sugiera cambios en su código, lo que asegurará la mejor interoperabilidad y compatibilidad con versiones posteriores de PHP de su código.Desde PHP 5 pero no incluidoenE_ALLhasta PHP 5.4.0
4096E_RECOVERABLE_ERROR(integer)Error fatal capturable. Indica que ocurrió un error probablemente peligroso, pero no dejó al Motor en un estado inestable. Si no se captura el error mediante un gestor definido por el usuario (vea tambiénset_error_handler()), la aplicación se abortará como si fuera unE_ERROR.Desde PHP 5.2.0
8192E_DEPRECATED(integer)Avisos en tiempo de ejecución. Habilítelo para recibir avisos sobre código que no funcionará en futuras versiones.Desde PHP 5.3.0
16384E_USER_DEPRECATED(integer)Mensajes de advertencia generados por el usuario. Son como unE_DEPRECATED, excepto que es generado por código de PHP mediante el uso de la función de PHPtrigger_error().Desde PHP 5.3.0
32767E_ALL(integer)Todos los errores y advertencias soportados, excepto del nivelE_STRICTantes de PHP 5.4.0.32767 en PHP 5.4.x, 30719 en PHP 5.3.x, 6143 en PHP 5.2.x, 2047 anteriormente

Los valores de arriba (numéricos o simbólicos) se usan para construir una máscara de bits que especifica qué errores notificar. Se pueden usar losoperadores a nivel de bitpara combinar estos valores o para enmascarar ciertos tipos de errores. Observe que sólo serán interpretados '|', '~', '!', '^' y '&' dentro dephp.ini.



Ejemplos

Abajo podemos ver un ejemplo del uso de las capacidades del manejo de errores de PHP. Definimos una función de gestión de errores que registra la información en un archivo (usado un foramto XML), y envía un e-mail a los desarrolladores en caso de que suceda un error crítico en la lógica.

Ejemplo #1 Usar el manejo de errores en un script

<?php
// haremos nuestro propio manejo de errores
error_reporting(0);

// función de gestión de errores definida por el usuario
functiongestorErrores($númerr,$menserr,$nombrearchivo,$númlínea,$vars)
{
// marca de tiempo para la entrada del error
$fh=date("Y-m-d H:i:s (T)");

// definir una matriz asociativa de cadena de error
// en realidad las únicas entradas que deberíamos
// considerar son E_WARNING, E_NOTICE, E_USER_ERROR,
// E_USER_WARNING y E_USER_NOTICE
$tipoerror= array (
E_ERROR=>'Error',
E_WARNING=>'Warning',
E_PARSE=>'Parsing Error',
E_NOTICE=>'Notice',
E_CORE_ERROR=>'Core Error',
E_CORE_WARNING=>'Core Warning',
E_COMPILE_ERROR=>'Compile Error',
E_COMPILE_WARNING=>'Compile Warning',
E_USER_ERROR=>'User Error',
E_USER_WARNING=>'User Warning',
E_USER_NOTICE=>'User Notice',
E_STRICT=>'Runtime Notice',
E_RECOVERABLE_ERROR=>'Catchable Fatal Error'
);
// conjunto de errores por el cuál se guardará un seguimiento de una variable
$errores_usuario= array(E_USER_ERROR,E_USER_WARNING,E_USER_NOTICE);

$err="<errorentry>\n";
$err.="\t<datetime>".$fh."</datetime>\n";
$err.="\t<errornum>".$númerr."</errornum>\n";
$err.="\t<errortype>".$tipoerror[$númerr] ."</errortype>\n";
$err.="\t<errormsg>".$menserr."</errormsg>\n";
$err.="\t<scriptname>".$nombrearchivo."</scriptname>\n";
$err.="\t<scriptlinenum>".$númlínea."</scriptlinenum>\n";

if (
in_array($númerr,$errores_usuario)) {
$err.="\t<vartrace>".wddx_serialize_value($vars,"Variables") ."</vartrace>\n";
}
$err.="</errorentry>\n\n";

// para probar
// echo $err;

// guardar al registro de errores, y enviarme un e-mail si hay un error crítico de usuario
error_log($err,3,"/usr/local/php4/error.log");
if (
$númerr==E_USER_ERROR) {
mail("phpdev@example.com","Error Crítico de Usuario",$err);
}
}


function
distancia($vect1,$vect2)
{
if (!
is_array($vect1) || !is_array($vect2)) {
trigger_error("Parámetros incorrectos, se esperaba una matriz",E_USER_ERROR);
return
NULL;
}

if (
count($vect1) !=count($vect2)) {
trigger_error("Los vectores necesitan ser del mismo tamaño",E_USER_ERROR);
return
NULL;
}

for (
$i=0;$i<count($vect1);$i++) {
$c1=$vect1[$i];$c2=$vect2[$i];
$d=0.0;
if (!
is_numeric($c1)) {
trigger_error("La coordenada$idel vector 1 no es un número, se usará cero",
E_USER_WARNING);
$c1=0.0;
}
if (!
is_numeric($c2)) {
trigger_error("La coordenada$idel vector 2 no es un número, se usará cero",
E_USER_WARNING);
$c2=0.0;
}
$d+=$c2*$c2-$c1*$c1;
}
return
sqrt($d);
}

$gestor_error_antiguo=set_error_handler("gestorErrores");

// constante no definida, genera una advertencia
$t=NO_ESTOY_DEFINIDA;

// definir algunos "vectores"
$a= array(2,3,"foo");
$b= array(5.5,4.3, -1.6);
$c= array(1, -3);

// generar un error de usuario
$t1=distancia($c,$b) ."\n";

// generar otro error de usuario
$t2=distancia($b,"no soy una matriz") ."\n";

// generar una advertencia
$t3=distancia($a,$b) ."\n";

?>



Funciones de Manejo de Errores

Ver también

Véase tambiénsyslog().


debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtraceGenera un rastreo

Descripción

debug_backtrace(int$options= DEBUG_BACKTRACE_PROVIDE_OBJECT,int$limit= 0):array

debug_backtrace()genera un rastreo de PHP.

Parámetros

options

Desde 5.3.6, este parámetro es una mascara de bits para las siguientes opciones:

debug_backtrace()options
DEBUG_BACKTRACE_PROVIDE_OBJECTCompletar el índice "object" o no.
DEBUG_BACKTRACE_IGNORE_ARGSOmitir el índice "args" y por lo tanto todos los argumentos de las funciones/métodos para ahorrar memoria o no.
Antes de 5.3.6, el único valor reconocido estrueofalse, que es lo mismo que establecer y desestablecer la opciónDEBUG_BACKTRACE_PROVIDE_OBJECT.

limit

Desde 5.4.0, este parámetro puede ser usado para limitar el número de stack frames que se muestran. Por defecto (limit=0) imprime todos los stack frames.

Valores devueltos

Devuelve un array dearrayasociativos. Los posibles elementos devueltos son los siguientes:

Posibles elementos devueltos pordebug_backtrace()
NombreTipoDescripción
functionstringEl nombre de la función actual. Véase también__FUNCTION__.
lineintegerEl número de línea actual. Véase también__LINE__.
filestringEl nombre de archivo actual. Véase también__FILE__.
classstringEl nombre de laclaseactual. Véase también__CLASS__
objectobjectElobjetoactual.
typestringEl tipo de llamada actual. Si es una llamada a un método devuelve "->". Si es una llamada a un método estático devuelve "::". Si es una llamada a una función no se devuelve nada.
argsarrayDentro de una función se lista los argumentos de la función. Dentro de un archvo incluido se lista el nombre (o nombres) del archivo incluido.

Historial de cambios

VersiónDescripción
5.4.0Añadido el parámetro opcionallimit.
5.3.6Se cambió el parámetroprovide_objectaoptionsy se añadió la opción adicionalDEBUG_BACKTRACE_IGNORE_ARGS.
5.2.5Se añadió el parámetro opcionalprovide_object.
5.1.1Se añadió elobjectactual como posible elemento devuelto.

Ejemplos

Ejemplo #1 Ejemplo dedebug_backtrace()

<?php
// nombre de archivo: /tmp/a.php

functionuna_prueba($str)
{
echo
"\nHola:$str";
var_dump(debug_backtrace());
}

una_prueba('amigo');
?>

<?php
// nombre de archivo: /tmp/b.php
include_once'/tmp/a.php';
?>

El resultado es similar al siguiente cuando se ejecuta/tmp/b.php:

Hola: amigo
array(2) {
[0]=>
array(4) {
    ["file"] => string(10) "/tmp/a.php"
    ["line"] => int(10)
    ["function"] => string(10) "una_prueba"
    ["args"]=>
    array(1) {
      [0] => &string(5) "amigo"
    }
}
[1]=>
array(4) {
    ["file"] => string(10) "/tmp/b.php"
    ["line"] => int(2)
    ["args"] =>
    array(1) {
      [0] => string(10) "/tmp/a.php"
    }
    ["function"] => string(12) "include_once"
  }
}

Ver también



debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtraceMuestra un rastreo

Descripción

debug_print_backtrace(int$options= 0,int$limit= 0):void

debug_print_backtrace()muestra un rastreo PHP. muestra las llamadas a función, archivos incluídos y el material evaluado medianteeval().

Parámetros

options

Desde 5.3.6, este parámetro es una máscara de bits para las siguientes opciones:

Opciones dedebug_print_backtrace()
DEBUG_BACKTRACE_IGNORE_ARGSOmitir el índice "args" y por lo tanto todos los argumentos de las funciones/métodos para ahorrar memoria o no.

limit

Desde 5.4.0, este parámetro puede ser usado para limitar el número de stack frames que se muestran. Por defecto (limit=0) imprime todos los stack frames.

Valores devueltos

No devuelve ningún valor.

Historial de cambios

VersiónDescripción
5.4.0Añadido el parámetro opcionallimit.
5.3.6Añadido el parámetro opcionaloptions.

Ejemplos

Ejemplo #1 Ejemplo dedebug_print_backtrace()

<?php
// archivo include.php
functiona() {
b();
}

function
b() {
c();
}

function
c(){
debug_print_backtrace();
}

a();

?>
<?php
// archivo prueba.php
// este es el archivo que debe ejecutar

include'include.php';
?>

El resultado del ejemplo sería algo similar a:

#0  c() called at [/tmp/include.php:10]
#1  b() called at [/tmp/include.php:6]
#2  a() called at [/tmp/include.php:17]
#3  include(/tmp/include.php) called at [/tmp/prueba.php:3]

Ver también



error_clear_last

(PHP 7, PHP 8)

error_clear_lastLimpiar el error más reciente

Descripción

error_clear_last():void

Valores devueltos

Limpia los errores más recientes, no pudiéndose recuperarlos así conerror_get_last().

Ejemplos

Ejemplo #1 Un ejemplo deerror_clear_last()

<?php
var_dump
(error_get_last());
error_clear_last();
var_dump(error_get_last());

@
$a=$b;

var_dump(error_get_last());
error_clear_last();
var_dump(error_get_last());
?>

El resultado del ejemplo sería algo similar a:

NULL
NULL
array(4) {
  ["type"]=>
  int(8)
  ["message"]=>
  string(21) "Undefined variable: b"
  ["file"]=>
  string(9) "%s"
  ["line"]=>
  int(6)
}
NULL



error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_lastObtener el último error que ocurrió

Descripción

error_get_last():array

Obtiene información sobre el último error que ocurrió.

Valores devueltos

Devuelve una matriz asociativa describiendo el último error con las claves "type" (tipo), "message" (mensaje), "file" (archivo) y "line" (línea). Si el error ha sido causado por una función interna de PHP, el "message" (mensaje) comienza con su nombre. Devuelvenullsi no ha habido aún un error.

Ejemplos

Ejemplo #1 Un ejemplo deerror_get_last()

<?php
echo$a;
print_r(error_get_last());
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [type] => 8
    [message] => Undefined variable: a
    [file] => C:\WWW\index.php
    [line] => 2
)



error_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_logEnviar un mensaje de error a las rutinas de manejo de errores definidas

Descripción

error_log(
    string$message,
    int$message_type= 0,
    string$destination= ?,
    string$extra_headers= ?
):bool

Envía un mensaje de error al registro de errores del servidor web o a un fichero.

Parámetros

message

El mensaje de error que debería ser registrado.

message_type

Indica dónde debería ir el error. Los tipos de mensaje posibles son:

Tipos de registro deerror_log()
0messagees enviado al registro del sistema de PHP, usando el mecanismo de registro del Sistema Operativo o un fichero, dependiendo de qué directiva de configuración esté establecida enerror_log. Esta opción es la predeterminada.
1messagees enviado por email a la dirección del parámetrodestination. Este es el único tipo de mensaje donde se usa el cuarto parámetroextra_headers.
2Ya no es una opción.
3messagees añadido al final del ficherodestination. No se añade automáticamente una nueva línea al final del stringmessage.
4messagees enviado directamente al gestor de registro de la SAPI.

destination

El destino. Su significado depende del parámetromessage_typetal como se describió arriba.

extra_headers

Las cabeceras extra. Se usa cuando el parámetromessage_typeestá establecido a1. Este tipo de mensaje usa la misma función interna quemail().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Notas

Advertencia

error_log()no es seguro a nivel binario.messageserá truncado por un carácter null.

Sugerencia

messageno debería contener un carácter null. Observe quemessagepodría enviarse a un fichero, correo, syslog, etc. Use la función de conversión/escape apropiada,base64_encode(),rawurlencode()oaddslashes(), antes de llamar aerror_log().

Ejemplos

Ejemplo #1 Ejemplos deerror_log()

<?php
// Enviar una notificación al registro del servidor si no podemos
// conectarnos a la base de datos.
if (!Ora_Logon($username,$password)) {
error_log("¡La base de datos de Oracle no está disponible!",0);
}

// Notificar al administrador mediante un email si agotamos FOO
if (!($foo=allocate_new_foo())) {
error_log("Problema serio, nos hemos quedado sin FOOs!",1,
"operator@example.com");
}

// otra manera de llamar a error_log():
error_log("¡Lo echaste a perder!",3,"/var/tmp/my-errors.log");
?>

Historial de cambios

VersiónDescripción
5.2.7El valor posible de 4 se añadió amessage_type.



error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reportingEstablece cuáles errores de PHP son notificados

Descripción

error_reporting(int$level= ?):int

La funciónerror_reporting()establece la directivaerror_reportingen tiempo de ejecución. PHP tiene varios niveles de errores para notificar, al utilizar ésta función se define el nivel de duración (tiempo de ejecución) de sus scripts. Si el parámetro opcionallevelno se define, la funciónerror_reporting()sólo devolverá el nivel actual de notificación de error.

Parámetros

level

El nuevo nivel deerror_reporting. Este nivel toma una máscara de bit o constantes nominadas. Al utilizar constantes nominadas se recomienda encarecidamente asegurar la compatibilidad para versiones futuras. Según se añaden niveles de error, el rango de los enteros incrementa, por lo que los niveles antiguos de errores basados en enteros no siempre se comportarán como se esperaba.

Las constantes de niveles de error disponibles, y los significados actuales de esos niveles de error están descritos enconstantes predefinidas.

Valores devueltos

Devuelve el nivel antiguo deerror_reportingo el nivel actual si el parámetrolevelno se proporciona.

Historial de cambios

VersiónDescripción
5.4.0AhoraE_STRICTes parte deE_ALL.
5.3.0Se introdujoE_DEPRECATEDyE_USER_DEPRECATED.
5.2.0Se introdujoE_RECOVERABLE_ERROR.

Ejemplos

Ejemplo #1 Ejemplos deerror_reporting()

<?php

// Desactivar toda notificación de error
error_reporting(0);

// Notificar solamente errores de ejecución
error_reporting(E_ERROR|E_WARNING|E_PARSE);

// Notificar E_NOTICE también puede ser bueno (para informar de variables
// no inicializadas o capturar errores en nombres de variables ...)
error_reporting(E_ERROR|E_WARNING|E_PARSE|E_NOTICE);

// Notificar todos los errores excepto E_NOTICE
error_reporting(E_ALL^E_NOTICE);

// Notificar todos los errores de PHP (ver el registro de cambios)
error_reporting(E_ALL);

// Notificar todos los errores de PHP
error_reporting(-1);

// Lo mismo que error_reporting(E_ALL);
ini_set('error_reporting',E_ALL);

?>

Notas

Advertencia

La mayoría de erroresE_STRICTson evaluados en tiempo de compilación por lo que tales errores no se notifican en el fichero dondeerror_reportingse mejora al incluir los errores deE_STRICT(y viceversa).

Sugerencia

Al pasar el valor-1se mostrarán todos los errores posibles, incluso cuando se añadan nuevos niveles y constantes en futuras versiones de PHP. La constanteE_ALLtambién se comporta de esta forma en PHP 5.4.

Ver también



restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handlerRecupera la función de gestión de errores previa

Descripción

restore_error_handler():bool

Usada después de modificar la función de gestión de errores usandoset_error_handler(), para revertir al gestor de errores previo (el cual puede ser el incorporado o una función definida por el usuario).

Valores devueltos

Esta función siempre devuelvetrue.

Ejemplos

Ejemplo #1 Ejemplo derestore_error_handler()

Decidir siunserialize()causó un error, entonces recuperar el gestor de errores original.

<?php
functiongestor_unserialize($errno,$errstr)
{
echo
"Valor seriado inválido.\n";
}

$seriado='foo';
set_error_handler('gestor_unserialize');
$original=unserialize($seriado);
restore_error_handler();
?>

El resultado del ejemplo sería:

Valor seriado inválido.

Ver también



restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handlerRestaura la función de gestión de excepciones previamente definida

Descripción

restore_exception_handler():bool

Usada después de cambiar la función de gestión de excepciones al utilizarset_exception_handler(), para volver al gestor de excepciones anterior (el cuál puede ser la función interna o una definida por el usuario).

Valores devueltos

Esta función siempre devuelvetrue.

Ejemplos

Ejemplo #1 Ejemplo derestore_exception_handler()

<?php
functiongestor_excepciones_1(Exception $e)
{
echo
'['.__FUNCTION__.'] '.$e->getMessage();
}

function
gestor_excepciones_2(Exception $e)
{
echo
'['.__FUNCTION__.'] '.$e->getMessage();
}

set_exception_handler('gestor_excepciones_1');
set_exception_handler('gestor_excepciones_2');

restore_exception_handler();

throw new
Exception('Esto dispara el primer gestor de excepciones...');
?>

El resultado del ejemplo sería:

[gestor_excepciones_1] Esto dispara el primer gestor de excepciones...

Ver también



set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handlerEstablecer una función de gestión de errores definida por el usuario

Descripción

set_error_handler(callable$error_handler,int$error_types= E_ALL | E_STRICT):mixed

Establece una función de usuario (error_handler) para manejar los errores de un script.

Esta función se puede usar para definir su propia forma de manejar los errores en tiempo de ejecución, por ejemplo en aplicaciones en las que se necesita hacer una limpieza de datos/archivos cuando ocurre un error crítico, o cuando se necesita provocar un error bajo ciertas condiciones (usandotrigger_error()).

Es importante recordar que el gestor de errores estándar de PHP es completamente evitado por los tipos de errores especificados porerror_typesa menos que la función de llamada de retorno devuelvafalse. La configuración deerror_reporting()no tendrá efecto y su gestor de errores será llamado de todas formas - aunque aún es capaz de leer el valor actual deerror_reportingy actuar de manera apropiada. En particular, observe que este valor será 0 si a la sentencia que causó el error se le añadió al principio eloperador de control de errores @.

También observe que es su responsabilidad realizar undie()si fuera necesario. Si la función de gestión de errores devuelve, la ejecución del script continuará con la siguiente sentencia después de la que causó el error.

Los siguientes tipos de errores no pueden ser manejados con una función definida por el usuario:E_ERROR,E_PARSE,E_CORE_ERROR,E_CORE_WARNING,E_COMPILE_ERROR,E_COMPILE_WARNING, y la mayoría deE_STRICTocasionados en el archivo desde donde se llamó aset_error_handler().

Si sucede algún error antes de que el script sea ejecutado (p.ej. en la carga de archivos) el gestor de errores personalizado no podrá ser llamado ya que no está registrado en ese momento.

Parámetros

error_handler

Una llamada de retorno con la siguiente signatura. Se podría pasarnullen su lugar para reiniciar este gestor a su estado predeterminado. También se puede proporcionar un nombre de una función, un array que contenga una referencia a un objeto y un nombre de un método.

handler(
    int$errno,
    string$errstr,
    string$errfile= ?,
    int$errline= ?,
    array$errcontext= ?
):bool
errno
El primer parámetro,errno, contiene el nivel del error ocasionado, como un valor de tipo integer.
errstr
El segundo parámetro,errstr, contiene el mensaje de error, como cadena.
errfile
El tercer parámetro es opcional,errfile, que contiene el nombre de archivo que ocasionó el error, como cadena.
errline
El cuarto parámetro es opcional,errline, que contiene el número de línea donde ocurrió el error, como valor de tipo integer.
errcontext
El quinto parámetro es opcional,errcontext, el cuál es una matriz que apunta a la tabla de símbolos activa en el punto donde ocurrió el error. En otras palabras,errcontextcontendrá una matriz con cada variable que existe en el ámbito donde el error fue provocado. El gestor de errores de usuario no debe modificar el contexto del error.

Si la función devuelvefalsese continúa con el gestor de errores normal.

error_types

Se puede usar para enmascarar la provocación de la funciónerror_handleral igual que la configuraciónerror_reportingini controla los errores que se muestran. Sin esta máscara establecidaerror_handlerserá llamada para cada error sin tener en cuenta la configuración deerror_reporting.

Valores devueltos

Devuelve una cadena que contiene el gestor de errores definido anteriormente (si lo hay). Si se usa el gestor de errores interno se devuelvenull.nulltambién es devuelto en caso de un error como una llamada de retorno no válida. Si el gestor de errores anterior era un método de una clase, esta función devolverá una matriz indexada con los nombres de las clases y métodos.

Historial de cambios

VersiónDescripción
5.5.0error_handlerahora aceptanull.
5.2.0El gestor de errores debe devolverfalsepara rellenar$php_errormsg.

Ejemplos

Ejemplo #1 Manejo de errores conset_error_handler()ytrigger_error()

El ejemplo de abajo muestra el manejo de excepciones internas mediante la provocación de errores y tratándolos con una función definida por el usuario:

<?php
// función de gestión de errores
functionmiGestorDeErrores($errno,$errstr,$errfile,$errline)
{
if (!(
error_reporting() &$errno)) {
// Este código de error no está incluido en error_reporting
return;
}

switch (
$errno) {
case
E_USER_ERROR:
echo
"<b>Mi ERROR</b> [$errno]$errstr<br />\n";
echo
" Error fatal en la línea$errlineen el archivo$errfile";
echo
", PHP ".PHP_VERSION." (".PHP_OS.")<br />\n";
echo
"Abortando...<br />\n";
exit(
1);
break;

case
E_USER_WARNING:
echo
"<b>Mi WARNING</b> [$errno]$errstr<br />\n";
break;

case
E_USER_NOTICE:
echo
"<b>Mi NOTICE</b> [$errno]$errstr<br />\n";
break;

default:
echo
"Tipo de error desconocido: [$errno]$errstr<br />\n";
break;
}

/* No ejecutar el gestor de errores interno de PHP */
returntrue;
}

// función para probar el manejo de errores
functionscale_by_log($vect,$scale)
{
if (!
is_numeric($scale) ||$scale<=0) {
trigger_error("log(x) para x <= 0 no está definido, usó: scale =$scale",E_USER_ERROR);
}

if (!
is_array($vect)) {
trigger_error("Vector de entrada incorrecto, se esperaba una matriz de valores",E_USER_WARNING);
return
null;
}

$temp= array();
foreach(
$vectas$pos=>$valor) {
if (!
is_numeric($valor)) {
trigger_error("El valor en la posición$posno es un número, usando 0 (cero)",E_USER_NOTICE);
$valor=0;
}
$temp[$pos] =log($scale) *$valor;
}

return
$temp;
}

// establecer el gestro de errores definido por el usuario
$gestor_errores_antiguo=set_error_handler("miGestorDeErrores");

// provocar algunos errores, primero definimos una matriz mixta con un elemento no numérico
echo"vector a\n";
$a= array(2,3,"foo",5.5,43.3,21.11);
print_r($a);

// ahora generamos una segunda matriz
echo"----\nvector b - a notice (b = log(PI) * a)\n";
/* Value at position $pos is not a number, using 0 (zero) */
$b=scale_by_log($a,M_PI);
print_r($b);

// esto es un problema, pasamos una cadena en vez de una matriz
echo"----\nvector c - a warning\n";
/* Vector de entrada incorrecto, se esperaba una matriz de valores */
$c=scale_by_log("no array",2.3);
var_dump($c);// NULL

// esto es un error crítico, log de cero o de un número negativo es indefinido
echo"----\nvector d - fatal error\n";
/* log(x) para x <= 0 no está definido, usó: scale = $scale */
$d=scale_by_log($a, -2.5);
var_dump($d);// Nunca se alcanza
?>

El resultado del ejemplo sería algo similar a:

vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>Mi NOTICE</b> [1024] El valor en la posición 2 no es un número, usando 0 (cero)<br />
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - a warning
<b>Mi WARNING</b> [512] Vector de entrada incorrecto, se esperaba una matriz de valores<br />
NULL
----
vector d - fatal error
<b>Mi ERROR</b> [256] log(x) para x <= 0 no está definido, usó: scale = -2.5<br />
  Error fatal en la línea 35 en el archivo trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Abortando...<br />

Ver también



set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handlerEstablece una función de gestión de excepciones definida por el usuario

Descripción

set_exception_handler(callable$exception_handler):callable

Establece el manejador de excepciones predeterminado si una excepción no es capturada dentro de un bloque try/catch. La ejecución se detendrá después de la llamada aexception_handler.

Parámetros

exception_handler

Nombre de la función a llamar cuando ocurra una excepción no capturada. Es necesario que esta función de gestión acepte un parámetro, que será el objeto de excepción que fue lanzado. Esta es la firma del manejador:

handler(Exception$ex):void

Desde PHP 7, la mayoría de los errores se notifican lanzando excepcionesError, las cuales serán también capturadas por el manejador.ErroryExceptionimplementan la interfazThrowable. Esta es la signatura del manejador desde PHP 7:

handler(Throwable$ex):void

Se podría pasarnullen su lugar para reiniciar este manejador a su estado predeterminado.

Precaución

Observe que al proporcionar unaExceptionexplícita como tipo implicado al parámetroexen una retrollamada causará problemas con la jerarquía de excepciones cambiada en PHP 7.

Valores devueltos

Devuelve el nombre del manejador de excepciones definido anteriormente, onullen caso de error. Si no se definió un manejador anterior también devolveránull.

Historial de cambios

VersiónDescripción
7.0.0Cambiado el tipo de parámetro pasado aexception_handlerdeExceptionaThrowable
5.5.0Anteriormente, si se pasabanull, esta función devolvíatrue. Devuelve el manejador anterior desde PHP 5.5.0.

Ejemplos

Ejemplo #1 Ejemplo deset_exception_handler()

<?php
functionmanejador_excepciones($excepción) {
echo
"Excepción no capturada: ",$excepción->getMessage(),"\n";
}

set_exception_handler('manejador_excepciones');

throw new
Exception('Excepción No Capturada');
echo
"No Ejecutado\n";
?>

Ver también



trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_errorGenerar un mensaje de error/advertencia/aviso de nivel de usuario

Descripción

trigger_error(string$error_msg,int$error_type= E_USER_NOTICE):bool

Se usa para provocar una condición de error de usuario, se puede utilizar junto con el gestor de errores interno o con una función definida por el usuario que ha sido establecida como el nuevo gestor de errores (set_error_handler()).

Esta función es útil cuando se necesita generar una respuesta en particular a una excepción en tiempo de ejecución.

Parámetros

error_msg

El mensaje de error designado para este error. Está limitado a 1024 bytes de longitud. Cualquier carácter más allá de los 1024 será truncado.

error_type

El tipo de error designado para este error. Sólo funciona con la familia de constantes E_USER, y por defecto esE_USER_NOTICE.

Valores devueltos

Esta función devuelvefalsesi se especifica unerror_typeerróneo, si notrue.

Ejemplos

Ejemplo #1 Ejemplo detrigger_error()

Véaseset_error_handler()para un ejemplo más extenso.

<?php
if ($divisor==0) {
trigger_error("No se puede dividir por cero",E_USER_ERROR);
}
?>

Notas

Advertencia

Las entidades HTML enerror_msgno son escapadas. Usehtmlentities()en el mensaje si el error se va a mostrar en un navegador.

Ver también



user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_errorAlias detrigger_error()

Descripción

Esta función es un alias de:trigger_error().


Tabla de contenidos




Foreign Function Interface


Introducción

This extension allows the loading of shared libraries (.DLLor.so), calling of C functions and accessing of C data structures in pure PHP, without having to have deep knowledge of the Zend extension API, and without having to learn a third “intermediate” language. The public API is implemented as a single classFFIwith several static methods (some of them may be called dynamically), and overloaded object methods, which perform the actual interaction with C data.

Precaución

FFI is dangerous, since it allows to interface with the system on a very low level. The FFI extension should only be used by developers having a working knowledge of C and the used C APIs. To minimize the risk, the FFI API usage may be restricted with theffi.enablephp.inidirective.

Nota:

The FFI extension does not render the classic PHP extension API obsolete; it is merely provided for ad-hoc interfacing with C functions and data structures.

Sugerencia

Currently, accessing FFI data structures is significantly (about 2 times) slower than accessing native PHP arrays and objects. Therefore, it makes no sense to use the FFI extension for speed; however, it may make sense to use it to reduce memory consumption.



Instalación/Configuración

Tabla de contenidos


Requerimientos

This extension requires the» libffi libraryto be installed.



Instalación

To enable the FFI extension, PHP has to be configured with--with-ffi.

Windows users have to includephp_ffi.dllintophp.inito enable the FFI extension.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

FFI Opciones de configuración
NombrePor defectoCambiableHistorial de cambios
ffi.enable"preload"PHP_INI_SYSTEM 
ffi.preload""PHP_INI_SYSTEM 
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

ffi.enablestring

Allows enabling ("true") or disabling ("false") FFI API usage, or restricting it only to the CLI SAPI and preloaded files ("preload").

The FFI API restrictions only affect theFFIclass, but not overloaded functions ofFFI\CDataobjects. This means that it is possible to create someFFI\CDataobjects in preloaded files, and then to use these directly in PHP scripts.

ffi.preloadstring

Allows preloading of FFI bindings during startup, which is not possible withFFI::load()ifopcache.preload_useris set. This directive accepts aDIRECTORY_SEPARATORdelimited list of filenames. The preloaded bindings can be accessed by callingFFI::scope().



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Esta extensión no tiene ninguna constante definida.



Ejemplos

Tabla de contenidos


Basic FFI usage

Before diving into the details of the FFI API, lets take a look at a few examples demonstrating the simplicity of the FFI API usage for regular tasks.

Nota:

Some of these examples requirelibc.so.6and as such will not work on systems where it is not available.

Ejemplo #1 Calling a function from shared library

<?php
// create FFI object, loading libc and exporting function printf()
$ffi=FFI::cdef(
"int printf(const char *format, ...);",// this is a regular C declaration
"libc.so.6");
// call C's printf()
$ffi->printf("Hello %s!\n","world");
?>

El resultado del ejemplo sería:

Hello world!

Nota:

Note that some C functions need specific calling conventions, e.g.__fastcall,__stdcallor,__vectorcall.

Ejemplo #2 Calling a function, returning a structure through an argument

<?php
// create gettimeofday() binding
$ffi=FFI::cdef("
typedef unsigned int time_t;
typedef unsigned int suseconds_t;

struct timeval {
time_t tv_sec;
suseconds_t tv_usec;
};

struct timezone {
int tz_minuteswest;
int tz_dsttime;
};

int gettimeofday(struct timeval *tv, struct timezone *tz);
"
,"libc.so.6");
// create C data structures
$tv=$ffi->new("struct timeval");
$tz=$ffi->new("struct timezone");
// call C's gettimeofday()
var_dump($ffi->gettimeofday(FFI::addr($tv),FFI::addr($tz)));
// access field of C data structure
var_dump($tv->tv_sec);
// print the whole C data structure
var_dump($tz);
?>

El resultado del ejemplo sería algo similar a:

int(0)
int(1555946835)
object(FFI\CData:struct timezone)#3 (2) {
  ["tz_minuteswest"]=>
  int(0)
  ["tz_dsttime"]=>
  int(0)
}

Ejemplo #3 Accessing existing C variables

<?php
// create FFI object, loading libc and exporting errno variable
$ffi=FFI::cdef(
"int errno;",// this is a regular C declaration
"libc.so.6");
// print C's errno
var_dump($ffi->errno);
?>

El resultado del ejemplo sería:

int(0)

Ejemplo #4 Creating and Modifying C variables

<?php
// create a new C int variable
$x=FFI::new("int");
var_dump($x->cdata);

// simple assignment
$x->cdata=5;
var_dump($x->cdata);

// compound assignment
$x->cdata+=2;
var_dump($x->cdata);
?>

El resultado del ejemplo sería:

int(0)
int(5)
int(7)

Ejemplo #5 Working with C arrays

<?php
// create C data structure
$a=FFI::new("long[1024]");
// work with it like with a regular PHP array
for ($i=0;$i<count($a);$i++) {
$a[$i] =$i;
}
var_dump($a[25]);
$sum=0;
foreach (
$aas$n) {
$sum+=$n;
}
var_dump($sum);
var_dump(count($a));
var_dump(FFI::sizeof($a));
?>

El resultado del ejemplo sería:

int(25)
int(523776)
int(1024)
int(8192)

Ejemplo #6 Working with C enums

<?php
$a
=FFI::cdef('typedef enum _zend_ffi_symbol_kind {
ZEND_FFI_SYM_TYPE,
ZEND_FFI_SYM_CONST = 2,
ZEND_FFI_SYM_VAR,
ZEND_FFI_SYM_FUNC
} zend_ffi_symbol_kind;
'
);
var_dump($a->ZEND_FFI_SYM_TYPE);
var_dump($a->ZEND_FFI_SYM_CONST);
var_dump($a->ZEND_FFI_SYM_VAR);
?>

El resultado del ejemplo sería:

int(0)
int(2)
int(3)



PHP Callbacks

It is possible to assign a PHP closure to a native variable of function pointer type or to pass it as a function argument:

<?php
$zend
=FFI::cdef("
typedef int (*zend_write_func_t)(const char *str, size_t str_length);
extern zend_write_func_t zend_write;
"
);

echo
"Hello World 1!\n";

$orig_zend_write= clone$zend->zend_write;
$zend->zend_write= function($str,$len) {
global
$orig_zend_write;
$orig_zend_write("{\n\t",3);
$ret=$orig_zend_write($str,$len);
$orig_zend_write("}\n",2);
return
$ret;
};
echo
"Hello World 2!\n";
$zend->zend_write=$orig_zend_write;
echo
"Hello World 3!\n";
?>

El resultado del ejemplo sería:

Hello World 1!
{
        Hello World 2!
}
Hello World 3!
Although this works, this functionality is not supported on all libffi platforms, is not efficient and leaks resources by the end of request.
Sugerencia

It is therefore recommended to minimize the usage of PHP callbacks.



A Complete PHP/FFI/preloading Example

php.ini

ffi.enable=preload
opcache.preload=preload.php

preload.php

<?php
FFI
::load(__DIR__."/dummy.h");
opcache_compile_file(__DIR__."/dummy.php");
?>

dummy.h

#define FFI_SCOPE "DUMMY"
#define FFI_LIB "libc.so.6"
 
int printf(const char *format, ...);

dummy.php

<?php
final classDummy{
private static
$ffi=null;
function
__construct() {
if (
is_null(self::$ffi)) {
self::$ffi=FFI::scope("DUMMY");
}
}
function
printf($format, ...$args) {
return (int)
self::$ffi->printf($format, ...$args);
}
}
?>

test.php

<?php
$d
= newDummy();
$d->printf("Hello %s!\n","world");
?>



Main interface to C code and data

(PHP 7 >= 7.4.0, PHP 8)

Introducción

Objects of this class are created by the factory methodsFFI::cdef(),FFI::load()orFFI::scope(). Defined C variables are made available as properties of the FFI instance, and defined C functions are made available as methods of the FFI instance. Declared C types can be used to create new C data structures usingFFI::new()andFFI::type().

FFI definition parsing and shared library loading may take significant time. It is not useful to do it on each HTTP request in a Web environment. However, it is possible to preload FFI definitions and libraries at PHP startup, and to instantiate FFI objects when necessary. Header files may be extended with specialFFI_SCOPEdefines (e.g.#define FFI_SCOPE "foo"”"; the default scope is "C") and then loaded byFFI::load()during preloading. This leads to the creation of a persistent binding, that will be available to all the following requests throughFFI::scope(). Refer to thecomplete PHP/FFI/preloading examplefor details.

It is possible to preload more than one C header file into the same scope.

Sinopsis de la Clase

finalclassFFI{
/* Constantes */
publicconstint__BIGGEST_ALIGNMENT__;
/* Métodos */
publicstaticaddr(FFI\CData&$ptr):FFI\CData
publicstaticalignof(FFI\CData|FFI\CType&$ptr):int
publicstaticarrayType(FFI\CType$type,array$dimensions):FFI\CType
publicstaticcast(FFI\CType|string$type,FFI\CData|int|float|bool|null&$ptr):?FFI\CData
publiccast(FFI\CType|string$type,FFI\CData|int|float|bool|null&$ptr):?FFI\CData
publicstaticcdef(string$code= "",?string$lib=null):FFI
publicstaticfree(FFI\CData&$ptr):void
publicstaticisNull(FFI\CData&$ptr):bool
publicstaticload(string$filename):?FFI
publicstaticmemcmp(string|FFI\CData&$ptr1,string|FFI\CData&$ptr2,int$size):int
publicstaticmemcpy(FFI\CData&$to,FFI\CData|string&$from,int$size):void
publicstaticmemset(FFI\CData&$ptr,int$value,int$size):void
publicstaticnew(FFI\CType|string$type,bool$owned=true,bool$persistent=false):?FFI\CData
publicnew(FFI\CType|string$type,bool$owned=true,bool$persistent=false):?FFI\CData
publicstaticscope(string$name):FFI
publicstaticsizeof(FFI\CData|FFI\CType&$ptr):int
publicstaticstring(FFI\CData&$ptr,?int$size=null):string
publicstatictype(string$type):?FFI\CType
publictype(string$type):?FFI\CType
publicstatictypeof(FFI\CData&$ptr):FFI\CType
}

Constantes predefinidas

FFI::__BIGGEST_ALIGNMENT__


FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addrCreates an unmanaged pointer to C data

Descripción

publicstaticFFI::addr(FFI\CData&$ptr):FFI\CData

Creates an unmanaged pointer to the C data represented by the givenFFI\CData. The sourceptrmust survive the resulting pointer. This function is mainly useful to pass arguments to C functions by pointer.

Parámetros

ptr

The handle of the pointer to a C data structure.

Valores devueltos

Returns the freshly createdFFI\CDataobject.



FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignofGets the alignment

Descripción

publicstaticFFI::alignof(FFI\CData|FFI\CType&$ptr):int

Gets the alignment of the givenFFI\CDataorFFI\CTypeobject.

Parámetros

ptr

The handle of the C data or type.

Valores devueltos

Returns the alignment of the givenFFI\CDataorFFI\CTypeobject.



FFI::arrayType

(PHP 7 >= 7.4.0, PHP 8)

FFI::arrayTypeDynamically constructs a new C array type

Descripción

publicstaticFFI::arrayType(FFI\CType$type,array$dimensions):FFI\CType

Dynamically constructs a new C array type with elements of type defined bytype, and dimensions specified bydimensions. In the following example$t1and$t2are equivalent array types:

<?php
$t1
=FFI::type("int[2][3]");
$t2=FFI::arrayType(FFI::type("int"), [2,3]);
?>

Parámetros

type

A valid C declaration asstring, or an instance ofFFI\CTypewhich has already been created.

dimensions

The dimensions of the type asarray.

Valores devueltos

Returns the freshly createdFFI\CTypeobject.



FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::castPerforms a C type cast

Descripción

publicstaticFFI::cast(FFI\CType|string$type,FFI\CData|int|float|bool|null&$ptr):?FFI\CData
publicFFI::cast(FFI\CType|string$type,FFI\CData|int|float|bool|null&$ptr):?FFI\CData

FFI::cast()creates a newFFI\CDataobject, that references the same C data structure, but is associated with a different type. The resulting object does not own the C data, and the sourceptrmust survive the result. The C type may be specified as astringwith any valid C type declaration or asFFI\CTypeobject, created before. If this method is called statically, it must only use predefined C type names (e.g.int,char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

Parámetros

type

A valid C declaration asstring, or an instance ofFFI\CTypewhich has already been created.

ptr

The handle of the pointer to a C data structure.

Valores devueltos

Returns the freshly createdFFI\CDataobject.



FFI::cdef

(PHP 7 >= 7.4.0, PHP 8)

FFI::cdefCreates a new FFI object

Descripción

publicstaticFFI::cdef(string$code= "",?string$lib=null):FFI

Creates a new FFI object.

Parámetros

code

A string containing a sequence of declarations in regular C language (types, structures, functions, variables, etc). Actually, this string may be copy-pasted from C header files.

Nota:

C preprocessor directives are not supported, i.e.#include,#defineand CPP macros do not work.

lib

The name of a shared library file, to be loaded and linked with the definitions.

Nota:

Iflibis omitted, platforms supportingRTLD_DEFAULTattempt to lookup symbols declared incodein the normal global scope. Other systems will fail to resolve these symbols.

Valores devueltos

Returns the freshly createdFFIobject.

Historial de cambios

VersiónDescripción
8.0.0libis nullable now.


FFI::free

(PHP 7 >= 7.4.0, PHP 8)

FFI::freeReleases an unmanaged data structure

Descripción

publicstaticFFI::free(FFI\CData&$ptr):void

Manually releases a previously created unmanaged data structure.

Parámetros

ptr

The handle of the unmanaged pointer to a C data structure.

Valores devueltos

No devuelve ningún valor.



FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNullChecks whether a FFI\CData is a null pointer

Descripción

publicstaticFFI::isNull(FFI\CData&$ptr):bool

Checks whether a FFI\CData is a null pointer.

Parámetros

ptr

The handle of the pointer to a C data structure.

Valores devueltos

Returns whether a FFI\CData is a null pointer.



FFI::load

(PHP 7 >= 7.4.0, PHP 8)

FFI::loadLoads C declarations from a C header file

Descripción

publicstaticFFI::load(string$filename):?FFI

Loads C declarations from a C header file. It is possible to specify shared libraries that should be loaded, using specialFFI_LIBdefines in the loaded C header file.

Parámetros

filename

The name of a C header file.

C preprocessor directives are not supported, i.e.#include,#defineand CPP macros do not work, except for special cases listed below.

The header fileshouldcontain a#definestatement for theFFI_SCOPEvariable, e.g.:#define FFI_SCOPE "MYLIB". Refer to theclass introductionfor details.

The header filemaycontain a#definestatement for theFFI_LIBvariable to specify the library it exposes. If it is a system library only the file name is required, e.g.:#define FFI_LIB "libc.so.6". If it is a custom library, a relative path is required, e.g.:#define FFI_LIB "./mylib.so".

Valores devueltos

Returns the freshly createdFFIobject, ornullon failure.

Ver también

  • FFI::scope()- Instantiates an FFI object with C declarations parsed during preloading



FFI::memcmp

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcmpCompares memory areas

Descripción

publicstaticFFI::memcmp(string|FFI\CData&$ptr1,string|FFI\CData&$ptr2,int$size):int

Comparessizebytes from the memory areasptr1andptr2. Bothptr1andptr2can be any native data structures (FFI\CData) or PHPstrings.

Parámetros

ptr1

The start of one memory area.

ptr2

The start of another memory area.

size

The number of bytes to compare.

Valores devueltos

Returns <0if the contents of the memory area starting atptr1are considered less than the contents of the memory area starting atptr2, >0if the contents of the first memory area are considered greater than the second, and0if they are equal.



FFI::memcpy

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcpyCopies one memory area to another

Descripción

publicstaticFFI::memcpy(FFI\CData&$to,FFI\CData|string&$from,int$size):void

Copiessizebytes from the memory areafromto the memory areato.

Parámetros

to

The start of the memory area to copy to.

from

The start of the memory area to copy from.

size

The number of bytes to copy.

Valores devueltos

No devuelve ningún valor.



FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memsetFills a memory area

Descripción

publicstaticFFI::memset(FFI\CData&$ptr,int$value,int$size):void

Fillssizebytes of the memory area pointed to byptrwith the given bytevalue.

Parámetros

ptr

The start of the memory area to fill.

value

The byte to fill with.

size

The number of bytes to fill.

Valores devueltos

No devuelve ningún valor.



FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::newCreates a C data structure

Descripción

publicstaticFFI::new(FFI\CType|string$type,bool$owned=true,bool$persistent=false):?FFI\CData
publicFFI::new(FFI\CType|string$type,bool$owned=true,bool$persistent=false):?FFI\CData

Creates a native data structure of the given C type. If this method is called statically, it must only use predefined C type names (e.g.int,char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

Parámetros

type

typeis a valid C declaration asstring, or an instance ofFFI\CTypewhich has already been created.

owned

Whether to create owned (i.e. managed) or unmanaged data. Managed data lives together with the returnedFFI\CDataobject, and is released when the last reference to that object is released by regular PHP reference counting or GC. Unmanaged data should be released by callingFFI::free(), when no longer needed.

persistent

Whether to allocate the C data structure permanently on the system heap (usingmalloc()), or on the PHP request heap (usingemalloc()).

Valores devueltos

Returns the freshly createdFFI\CDataobject, ornullon failure.



FFI::scope

(PHP 7 >= 7.4.0, PHP 8)

FFI::scopeInstantiates an FFI object with C declarations parsed during preloading

Descripción

publicstaticFFI::scope(string$name):FFI

Instantiates an FFI object with C declarations parsed during preloading.

TheFFI::scope()method is safe to call multiple times for the same scope. Multiple references to the same scope may be loaded at the same time.

Parámetros

name

The scope name defined by a specialFFI_SCOPEdefine.

Valores devueltos

Returns the freshly createdFFIobject.

Ver también



FFI::sizeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::sizeofGets the size of C data or types

Descripción

publicstaticFFI::sizeof(FFI\CData|FFI\CType&$ptr):int

Returns the size of the givenFFI\CDataorFFI\CTypeobject.

Parámetros

ptr

The handle of the C data or type.

Valores devueltos

The size of the memory area pointed at byptr.



FFI::string

(PHP 7 >= 7.4.0, PHP 8)

FFI::stringCreates a PHP string from a memory area

Descripción

publicstaticFFI::string(FFI\CData&$ptr,?int$size=null):string

Creates a PHPstringfromsizebytes of the memory area pointed to byptr.

Parámetros

ptr

The start of the memory area from which to create astring.

size

The number of bytes to copy to thestring. Ifsizeis omitted,ptrmust be a zero terminated array of Cchars.

Valores devueltos

The freshly created PHPstring.

Historial de cambios

VersiónDescripción
8.0.0sizeis nullable now; previously, its default was0.


FFI::type

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeCreates an FFI\CType object from a C declaration

Descripción

publicstaticFFI::type(string$type):?FFI\CType
publicFFI::type(string$type):?FFI\CType

This function creates and returns aFFI\CTypeobject for the givenstringcontaining a C type declaration. If this method is called statically, it must only use predefined C type names (e.g.int,char, etc.); if the method is called as instance method, any type declared for the instance is allowed.

Parámetros

type

A valid C declaration asstring, or an instance ofFFI\CTypewhich has already been created.

Valores devueltos

Returns the freshly createdFFI\CTypeobject, ornullon failure.



FFI::typeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeofGets the FFI\CType of FFI\CData

Descripción

publicstaticFFI::typeof(FFI\CData&$ptr):FFI\CType

Gets theFFI\CTypeobject representing the type of the givenFFI\CDataobject.

Parámetros

ptr

The handle of the pointer to a C data structure.

Valores devueltos

Returns theFFI\CTypeobject representing the type of the givenFFI\CDataobject.


Tabla de contenidos



C Data Handles

(PHP 7 >= 7.4.0, PHP 8)

Introducción

FFI\CDataobjects can be used in a number of ways as a regular PHP data:

  • C data of scalar types can be read and assigned via the$cdataproperty, e.g.$x = FFI::new('int'); $x->cdata = 42;
  • C struct and union fields can be accessed as regular PHP object property, e.g.$cdata->field
  • C array elements can be accessed as regular PHP array elements, e.g.$cdata[$offset]
  • C arrays can be iterated usingforeachstatements.
  • C arrays can be used as arguments ofcount().
  • C pointers can be dereferenced as arrays, e.g.$cdata[0]
  • C pointers can be compared using regular comparison operators (<,<=,==,!=,>=,>).
  • C pointers can be incremented and decremented using regular+/-/++/–-operations, e.g.$cdata += 5
  • C pointers can be subtracted from another using regular-operations.
  • C pointers to functions can be called as a regular PHP closure, e.g.$cdata()
  • Any C data can be duplicated using thecloneoperator, e.g.$cdata2 = clone $cdata;
  • Any C data can be visualized usingvar_dump(),print_r(), etc.

Nota:Notable limitations are thatFFI\CDatainstances do not supportisset(),empty()andunset(), and that wrapped C structs and unions do not implementTraversable.

Sinopsis de la Clase

finalclassFFI\CData{
}


C Type Handles

(PHP 7 >= 7.4.0, PHP 8)

Introducción

Sinopsis de la Clase

finalclassFFI\CType{
/* Constantes */
publicconstintTYPE_VOID;
publicconstintTYPE_FLOAT;
publicconstintTYPE_DOUBLE;
publicconstintTYPE_LONGDOUBLE;
publicconstintTYPE_UINT8;
publicconstintTYPE_SINT8;
publicconstintTYPE_UINT16;
publicconstintTYPE_SINT16;
publicconstintTYPE_UINT32;
publicconstintTYPE_SINT32;
publicconstintTYPE_UINT64;
publicconstintTYPE_SINT64;
publicconstintTYPE_ENUM;
publicconstintTYPE_BOOL;
publicconstintTYPE_CHAR;
publicconstintTYPE_POINTER;
publicconstintTYPE_FUNC;
publicconstintTYPE_ARRAY;
publicconstintTYPE_STRUCT;
publicconstintATTR_CONST;
publicconstintATTR_INCOMPLETE_TAG;
publicconstintATTR_VARIADIC;
publicconstintATTR_INCOMPLETE_ARRAY;
publicconstintATTR_VLA;
publicconstintATTR_UNION;
publicconstintATTR_PACKED;
publicconstintATTR_MS_STRUCT;
publicconstintATTR_GCC_STRUCT;
publicconstintABI_DEFAULT;
publicconstintABI_CDECL;
publicconstintABI_FASTCALL;
publicconstintABI_THISCALL;
publicconstintABI_STDCALL;
publicconstintABI_PASCAL;
publicconstintABI_REGISTER;
publicconstintABI_MS;
publicconstintABI_SYSV;
publicconstintABI_VECTORCALL;
/* Métodos */
publicgetAlignment():int
publicgetArrayLength():int
publicgetAttributes():int
publicgetEnumKind():int
publicgetFuncABI():int
publicgetKind():int
publicgetName():string
publicgetSize():int
publicgetStructFieldNames():array
publicgetStructFieldOffset(string$name):int
publicgetStructFieldType(string$name):FFI\CType
}

Constantes predefinidas

FFI\CType::TYPE_VOID

FFI\CType::TYPE_FLOAT

FFI\CType::TYPE_DOUBLE

FFI\CType::TYPE_LONGDOUBLE

FFI\CType::TYPE_UINT8

FFI\CType::TYPE_SINT8

FFI\CType::TYPE_UINT16

FFI\CType::TYPE_SINT16

FFI\CType::TYPE_UINT32

FFI\CType::TYPE_SINT32

FFI\CType::TYPE_UINT64

FFI\CType::TYPE_SINT64

FFI\CType::TYPE_ENUM

FFI\CType::TYPE_BOOL

FFI\CType::TYPE_CHAR

FFI\CType::TYPE_POINTER

FFI\CType::TYPE_FUNC

FFI\CType::TYPE_ARRAY

FFI\CType::TYPE_STRUCT

FFI\CType::ATTR_CONST

FFI\CType::ATTR_INCOMPLETE_TAG

FFI\CType::ATTR_VARIADIC

FFI\CType::ATTR_INCOMPLETE_ARRAY

FFI\CType::ATTR_VLA

FFI\CType::ATTR_UNION

FFI\CType::ATTR_PACKED

FFI\CType::ATTR_MS_STRUCT

FFI\CType::ATTR_GCC_STRUCT

FFI\CType::ABI_DEFAULT

FFI\CType::ABI_CDECL

FFI\CType::ABI_FASTCALL

FFI\CType::ABI_THISCALL

FFI\CType::ABI_STDCALL

FFI\CType::ABI_PASCAL

FFI\CType::ABI_REGISTER

FFI\CType::ABI_MS

FFI\CType::ABI_SYSV

FFI\CType::ABI_VECTORCALL


FFI\CType::getAlignment

(PHP 8 >= 8.1.0)

FFI\CType::getAlignmentDescription

Descripción

publicFFI\CType::getAlignment():int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementTypeDescription

Descripción

publicFFI\CType::getArrayElementType():FFI\CType

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLengthDescription

Descripción

publicFFI\CType::getArrayLength():int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributesDescription

Descripción

publicFFI\CType::getAttributes():int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKindDescription

Descripción

publicFFI\CType::getEnumKind():int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABIDescription

Descripción

publicFFI\CType::getFuncABI():int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCountDescription

Descripción

publicFFI\CType::getFuncParameterCount():int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getFuncParameterType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterTypeDescription

Descripción

publicFFI\CType::getFuncParameterType(int$index):FFI\CType

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

index

Valores devueltos



FFI\CType::getFuncReturnType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncReturnTypeDescription

Descripción

publicFFI\CType::getFuncReturnType():FFI\CType

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKindDescription

Descripción

publicFFI\CType::getKind():int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getNameDescription

Descripción

publicFFI\CType::getName():string

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerTypeDescription

Descripción

publicFFI\CType::getPointerType():FFI\CType

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSizeDescription

Descripción

publicFFI\CType::getSize():int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNamesDescription

Descripción

publicFFI\CType::getStructFieldNames():array

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffsetDescription

Descripción

publicFFI\CType::getStructFieldOffset(string$name):int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

name

Valores devueltos



FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldTypeDescription

Descripción

publicFFI\CType::getStructFieldType(string$name):FFI\CType

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

name

Valores devueltos


Tabla de contenidos



FFI Exceptions

(PHP 7 >= 7.4.0, PHP 8)

Introducción

Sinopsis de la Clase

classFFI\ExceptionextendsError{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
}


FFI Parser Exceptions

(PHP 7 >= 7.4.0, PHP 8)

Introducción

Sinopsis de la Clase

finalclassFFI\ParserExceptionextendsFFI\Exception{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
}



OPcache


Introducción

OPcache mejora el rendimiento de PHP almacenando el código de bytes de un script precompilado en la memoria compartida, eliminando así la necesidad de que PHP cargue y analice los script en cada petición.

Esta extensión está incluída en PHP 5.5.0 y posteriores, y está» disponible en PECLpara las versiones 5.2, 5.3 y 5.4 de PHP.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

El proceso de instalación de OPcache varía dependiendo de la versión de PHP que se esté usando. Consulte la sección de abajo acorde a la versión que se esté empleando.

Nota:

Si fuera necesario utilizar OPcache con» Xdebug, se debe cargar OPcache antes que Xdebug.

PHP 5.5.0 y posteriores

OPcache solamente se podrá compilar como una extensión compartida. Si se ha deshabilitado la construcción de extensiones predeterminadas por medio de--disable-all, se debe compilar PHP con la la opción--enable-opcachepara que OPcache esté disponible.

Una vez compilada, se puede usar la directiva de configuraciónzend_extensionpara cargar la extensión OPcache en PHP. Esto se puede realizar por medio dezend_extension=/full/path/to/opcache.soen plataformas diferentes de Windows, y conzend_extension=C:\path\to\php_opcache.dllen Windows.

PHP 5.2, 5.3 y 5.4

Esta extensión» PECLno se distribuye con PHP.

Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/ZendOpcache.

Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.

Configuración php.ini recomendada

Se recomiendan generalmente las siguientes opciones para proveer un buen rendimiento:

opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=4000
opcache.revalidate_freq=60
opcache.fast_shutdown=1
opcache.enable_cli=1

Tambien se podría considerar deshabilitaropcache.save_commentsy habilitaropcache.enable_file_override, aunque se deberá probar el código antes de utilizarlas durante producción, ya que se sabe que causan problemas en marcos de trabajo y aplicaciones, particularmente en casos donde se utilizan anotaciones de comentarios en la documentación.

También está disponibleuna lista completa de directivas de configuración admitidas por OPcache.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Opciones de configuración de OPcache
NombrePor defectoCambiableHistorial de cambios
opcache.enable"1"PHP_INI_ALL 
opcache.enable_cli"0"PHP_INI_SYSTEMEntre PHP 7.1.2 y 7.1.6 inclusive, el valor predetermindao era "1"
opcache.memory_consumption"128"PHP_INI_SYSTEM 
opcache.interned_strings_buffer"8"PHP_INI_SYSTEM 
opcache.max_accelerated_files"10000"PHP_INI_SYSTEMAntes de PHP 7.0.0 el valor predeterminado era "2000"
opcache.max_wasted_percentage"5"PHP_INI_SYSTEM 
opcache.use_cwd"1"PHP_INI_SYSTEM 
opcache.validate_timestamps"1"PHP_INI_ALL 
opcache.revalidate_freq"2"PHP_INI_ALL 
opcache.revalidate_path"0"PHP_INI_ALL 
opcache.save_comments"1"PHP_INI_SYSTEM 
opcache.fast_shutdown"0"PHP_INI_SYSTEMEliminado en PHP 7.2.0.
opcache.enable_file_override"0"PHP_INI_SYSTEM 
opcache.optimization_level"0x7FFFBFFF"PHP_INI_SYSTEMCambiado desde 0xFFFFFFFF en PHP 5.6.18
opcache.inherited_hack"1"PHP_INI_SYSTEMEliminado en PHP 7.3.0.
opcache.dups_fix"0"PHP_INI_ALL 
opcache.blacklist_filename""PHP_INI_SYSTEM 
opcache.max_file_size"0"PHP_INI_SYSTEM 
opcache.consistency_checks"0"PHP_INI_ALL 
opcache.force_restart_timeout"180"PHP_INI_SYSTEM 
opcache.error_log""PHP_INI_SYSTEM 
opcache.log_verbosity_level"1"PHP_INI_SYSTEM 
opcache.record_warnings"0"PHP_INI_SYSTEMDisponible a partir de PHP 8.0.0
opcache.preferred_memory_model""PHP_INI_SYSTEM 
opcache.protect_memory"0"PHP_INI_SYSTEM 
opcache.mmap_basenullPHP_INI_SYSTEM 
opcache.restrict_api""PHP_INI_SYSTEM 
opcache.file_update_protection"2"PHP_INI_ALL 
opcache.huge_code_pages"0"PHP_INI_SYSTEM 
opcache.lockfile_path"/tmp"PHP_INI_SYSTEM 
opcache.opt_debug_level"0"PHP_INI_SYSTEMDisponible a partir de PHP 7.1.0
opcache.file_cacheNULLPHP_INI_SYSTEM 
opcache.file_cache_only"0"PHP_INI_SYSTEM 
opcache.file_cache_consistency_checks"1"PHP_INI_SYSTEM 
opcache.file_cache_fallback"1"PHP_INI_SYSTEMSolo Windows.
opcache.validate_permission"0"PHP_INI_SYSTEMDisponible a partir de PHP 7.0.14
opcache.validate_root"0"PHP_INI_SYSTEMDisponible a partir de PHP 7.0.14
opcache.preload""PHP_INI_SYSTEMDisponible a partir de PHP 7.4.0
opcache.preload_user""PHP_INI_SYSTEMDisponible a partir de PHP 7.4.0
opcache.cache_id""PHP_INI_SYSTEMSolo Windows. Disponible a partir de PHP 7.4.0
opcache.jit"tracing"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_buffer_size"0"PHP_INI_SYSTEMDisponible a partir de PHP 8.0.0
opcache.jit_debug"0"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_bisect_limit"0"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_prof_threshold"0.005"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_max_root_traces"1024"PHP_INI_SYSTEMDisponible a partir PHP 8.0.0
opcache.jit_max_side_traces"128"PHP_INI_SYSTEMDisponible a partir de PHP 8.0.0
opcache.jit_max_exit_counters"8192"PHP_INI_SYSTEMDisponible a partir de PHP 8.0.0
opcache.jit_hot_loop"64"PHP_INI_SYSTEMDisponible a partir de PHP 8.0.0
opcache.jit_hot_func"127"PHP_INI_SYSTEMDisponible a partir de PHP 8.0.0
opcache.jit_hot_return"8"PHP_INI_SYSTEMDisponible a partir de PHP 8.0.0
opcache.jit_hot_side_exit"8"PHP_INI_SYSTEMDisponible a partir de PHP 8.0.0
opcache.jit_blacklist_root_trace"16"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_blacklist_side_trace"8"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_max_loop_unrolls"8"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_max_recursive_calls"2"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_max_recursive_returns"2"PHP_INI_ALLDisponible a partir de PHP 8.0.0
opcache.jit_max_polymorphic_calls"2"PHP_INI_ALLDisponible a partir de PHP 8.0.0
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

opcache.enableboolean

Habilita la caché de opcode. Cuando está deshabilitado, el código no es optimizado o almacenado en caché. El ajusteopcache.enableno puede ser habilitado en tiempo de ejecución enabled at runtime a través deini_set(), solamente puede ser deshabilitado. Intentar habilitarlo en un script gernerará una advertencia.

opcache.enable_cliboolean

Habilita la caché de opcode para la versión CLI de PHP.

opcache.memory_consumptioninteger

EL tamaño del almacén de memoria compartida utilizado por OPcache, en megabytes.

opcache.interned_strings_bufferinteger

La cantidad de memoria utilizada para almacenar cadenas, en megabytes. Esta directiva de configuración es ignorada en PHP < 5.3.0.

opcache.max_accelerated_filesinteger

El número máximo de claves (y por lo tanto, de scripts) en la tabla de hash de OPcache. El valor que realmente se utilizará será el primer número en el conjunto de los números primos{ 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987 }que sea mayor o igual al valor configurado. El valor mínimo es 200. El valor máximo es 100000 en PHP < 5.5.6, y 1000000 en versiones posteriores.

opcache.max_wasted_percentageinteger

El porcentaje máximo de memoria desperdiciada que está permitida antes de que un reinicio sea programado.

opcache.use_cwdboolean

Si está habilitada, OPcache añade el directorio de trabajo actual a la clave del script, eliminado así las posibles colisiones entre ficheros con el mismo nombre base. Deshabilitar esta directiva mejora el rendimiento pero podría generar problemas en aplicaciones existentes.

opcache.validate_timestampsboolean

Si está habilitado, OPcache consultará por scripts actualizados cadaopcache.revalidate_freqsegundos. Cuando esta directiva está deshabilitada, se debe reiniciar OPcache de forma manual medianteopcache_reset(),opcache_invalidate()o reiniciando el servidor web para que los cambios en el sistema de ficheros tomen efecto.

opcache.revalidate_freqinteger

La frecuencia de verificación de las marcas temporales de Unix de los scripts por actualizaciones, en segundos.0hará que OPcache consulte por actualizaciones en cada petición.

Esta directiva de configuración es ignorada siopcache.validate_timestampsestá deshabilitada.

opcache.revalidate_pathboolean

Si está deshabilitada, los ficheros cacheados existentes que usen el mismoinclude_pathserán reutilizados. Por lo tanto, si un fichero con el mismo nombre está en algún otro lado del include_path, no será encontrado.

opcache.save_commentsboolean

Si está deshabilitada, todos los comentarios de la documentación serán elliminados de la caché de opcode para reducir el tamaño del código optimizado. Deshabilitar esta directiva de configuración podría generar problemas en aplicaciones y frameworks que dependen del análisis de comentarios para anotaciones, incluyendo Doctrine, Zend Framework 2 y PHPUnit.

opcache.load_commentsboolean

Si está deshabilitada, los comentarios de la documentación no serán cargados de la caché de opcode aun si éstos existen. Esto puede ser usado junto conopcache.save_commentspara cargar sólo los comentarios para las aplicaciones que los requieran.

opcache.fast_shutdownboolean

Si está habilitada, una secuencia de apagado rápida es utilizada que no libera cada bloque asignado sino que depende del gestor de memoria del Zend Engine para rescindir del conjunto de variables de petición completo.

Esta directiva ha sido eliminada en PHP 7.2.0. Se ha integrado una variante de la secuencia de apagado rápido en PHP, y será usada automáticamente si es posible.

opcache.enable_file_overrideboolean

Cuando está habilitada, la caché de opcode será consultado para determinar si un fichero ya ha sido cacheado cuandofile_exists(),is_file()yis_readable()son llamadas. Esto puede incrementar el rendimiento en aplicaciones que chequean la existencia y legibilidad de los scripts PHP, pero arriesgando devolver datos obsoletos siopcache.validate_timestampsestá deshabilitada.

opcache.optimization_levelinteger

Un bitmask que controla cúales permisos de optimización son ejecutados.

opcache.inherited_hackbool

Esta directiva de configuración es ignorada.

opcache.dups_fixboolean

Este hack debería estar habilitado para funcionar sólo para evitar errores "Cannot redeclare class".

opcache.blacklist_filenamestring

La ubicación del fichero de blacklist de OPcache. Un fichero blacklist es un texto que contiene los nombres de los ficheros que no deberían ser acelerados, uno por línea. Se permiten comodines, y prefijos también pueden ser provistos. Las líneas que comienzen con un punto y coma son ignoradas como comentarios.

Un fichero blacklist simple luciría así:

; Matches a specific file.
/var/www/broken.php
; A prefix that matches all files starting with x.
/var/www/x
; A wildcard match.
/var/www/*-broken.php
opcache.max_file_sizeinteger

El tamaño de fichero máximo que será almacenado en caché, en bytes. Si es0, todos los ficheros serán almacenados en caché.

opcache.consistency_checksinteger

Si es distinto de cero, OPcache verificará el checksum de la caché cada N peticiones, donde N es el valor de esta directiva de configuración. Esto debería sólo estar habilitado durante la depuración ya que puede tener un impacto negativo en el rendimiento.

opcache.force_restart_timeoutinteger

La cantidad de tiempo a esperar el comienzo de un reinicio programado si la caché no está activa, en segundos. Si se acaba el tiempo, entonces OPcache asume que algo anda mal y terminará todos los procesos que bloqueen la caché para permitir un reinicio.

Siopcache.log_verbosity_leveles 2 o más, una advertencia será guardada en el registro de errores si esto ocurre.

opcache.error_logstring

El registro de errores de errores de OPcache. Una cadena vacía es tratada de igual forma questderr, y resultará en registros siendo enviados a errores estándar (que será el registro de errores del servidor Web en la mayoría de los casos).

opcache.log_verbosity_levelinteger

El nivel de verbosidad del registro. Por defecto, sólo los errores fatales (nivel 0) y errores (nivel 1) son registrados. Otros niveles disponibles son advertencias (nivel 2), mensajes de información (nivel 3) y mensajes de depuración (nivel 4).

opcache.record_warningsbool

If enabled, OPcache will record compile-time warnings and replay them on the next include, even if it is served from cache.

opcache.preferred_memory_modelstring

El modelo de memoria principal que utilizará OPcache. Si se deja vacío, OPcache seleccionará el modelo más apropiado, el cual es el comportamiento correcto en prácticamente todos los casos.

Los valores posibles incluyenmmap,shm,posixywin32.

opcache.protect_memoryboolean

Protege la memoria compartida de escrituras inesperadas mientras se ejecutan scripts. Esto es útil sólo para depuración interna.

opcache.mmap_basestring

La base usada para los segmentos de memoria compartida en Windows. Todos los procesos PHP deben mapear la memoria compartida con el mismo espacio de direcciones. Utilizando esta directiva se corrigen los errores "Unable to reattach to base address".

opcache.restrict_apistring

Permite llamar a funciones de la API de OPcache solamente desde scripts de PHP cuya ruta comience con la cadena especificada. El valor predeterminado de "" significa sin restricciones.

opcache.file_update_protectionstring

Previene de almacenar en caché ficheros que estén menos que este número de segundos. Protege del almacenamiento en caché de ficheros no actualizados completamente. En caso de que todas las actualizaciones de ficheros del sitio sean atómicas, se puede aumentar el rendimiento estableciéndolo a "0".

opcache.huge_code_pagesstring

Habilita o inhabilita la copia de código de PHP (segmento de texto) a HUGE PAGES. Esto debería mejorar el rendimiento, aunque requiere una configuración apropiada del SO.

opcache.lockfile_pathstring

Ruta absoluta usada para almacenar shared lockfiles compartidos (solo para *nix)

opcache.opt_debug_levelstring

Produce volcados de opcode para depurar diferentes escenarios de optimización. 0x10000 generará opcodes a medida que el compilador los haya producido antes de ocurra cualquier optimización, mientras que 0x20000 generará códigos optimizados.

opcache.file_cachestring

Habilita y establece el segundo nivel de directorio de caché. Debería mejorar el rendimiento cuando la memoria SHM esté llena, cuando se reinicie el servidor o se restablezca la SHM. El valor predeterminado "" inhabilita el almacenamiento en cache basado en ficheros.

opcache.file_cache_onlyboolean

Habilita o inhabilita el almacenamiento de opcodes en memoria compartida.

opcache.file_cache_consistency_checksboolean

Habilita o inhabilita la validación del checksum cuando un script sea cargado desde la caché de ficheros.

opcache.file_cache_fallbackboolean

Implica opcache.file_cache_only=1 para ciertos procesos que fallan al volver a vincularse a la memoria conpartida (solo Windows). Es necesaria la caché de ficheros explícitamente.

Precaución

La inhabilitación de esta opción de configuración puede evitar el inicio de procesos, por lo que está desaconsejado.

opcache.validate_permissionboolean

Valida los permisos de ficheros almacenados en caché con el usuario en uso.

opcache.validate_rootboolean

Evita la colisión de nombres en entornos con chroot. Debe estar habilitado en todos los entornos con chroot para evitar el acceso a ficheros fuera de chroot.

opcache.preloadstring

Especifica un script de PHP que va a ser compilado y ejecutado en el arranque del servidor, lo que podría precargar otros ficheros, ya sea conincludeo usando la funciónopcache_compile_file(). Todas las entidades (p. ej. funciones y clases) definidas en estos ficheros estarán disponibles para peticiones listas para usar, hasta que el servidor sea apagado.

opcache.preload_userstring

La precarga de código como «root» no está permitida por razones de seguridad. Esta directiva facilita que la precarga se ejecute como otro usuario.

opcache.cache_idstring

On Windows, all processes running the samePHPSAPIunder the same user account having the same cache ID share a single OPcache instance. The value of the cache ID can be freely chosen.

Sugerencia

For IIS, different application pools can have their own OPcache instance by using the environment variableAPP_POOL_IDasopcache.cache_id.

opcache.jitstring|int

For typical usage, this option accepts one of four string values:

  • disable: Completely disabled, cannot be enabled at runtime.
  • off: Disabled, but can be enabled at runtime.
  • tracing/on: Use tracing JIT. Enabled by default and recommended for most users.
  • function: Use function JIT.

For advanced usage, this option accepts a 4-digit integerCRTO, where the digits mean:

C(CPU-specific optimization flags)
  • 0: Disable CPU-specific optimization.
  • 1: Enable use of AVX, if the CPU supports it.
R(register allocation)
  • 0: Don't perform register allocation.
  • 1: Perform block-local register allocation.
  • 2: Perform global register allocation.
T(trigger)
  • 0: Compile all functions on script load.
  • 1: Compile functions on first execution.
  • 2: Profile functions on first request and compile the hottest functions afterwards.
  • 3: Profile on the fly and compile hot functions.
  • 4: Currently unused.
  • 5: Use tracing JIT. Profile on the fly and compile traces for hot code segments.
O(optimization level)
  • 0: No JIT.
  • 1: Minimal JIT (call standard VM handlers).
  • 2: Inline VM handlers.
  • 3: Use type inference.
  • 4: Use call graph.
  • 5: Optimize whole script.
The"tracing"mode corresponds toCRTO = 1254, the"function"mode corresponds toCRTO = 1205.

opcache.jit_buffer_sizeint

The amount of shared memory to reserve for compiled JIT code. A zero value disables the JIT.

Cuando se usa uninteger, el valor del mismo es medido en bytes. También se puede usar la notación reducida, tal como se describe enesta FAQ.
opcache.jit_debugint

A bit mask specifying which JIT debug output to enable. For possible values, please consultzend_jit.h.

opcache.jit_bisect_limitint

Debugging option that disables JIT compilation after compiling a certain number of functions. This may be helpful to bisect the source of a JIT miscompilation. Note: this option only works when JIT trigger is set to 0 (compile on script load) or 1 (compile on first execution), e.g.,opcache.jit=1215. See more inopcache.jitoption.

opcache.jit_prof_thresholdfloat

When using the "profile on first request" trigger mode, this threshold determines whether a function is considered hot. The number of calls to the function divided by the number of calls to all functions must be above the threshold. For example, a threshold of 0.005 means that functions that made up more than 0.5% of all calls will be JIT compiled.

opcache.jit_max_root_tracesint

Maximum number of root traces. The root trace is an execution flow taking one path through the code firstly, which is a unit of JIT compilation. JIT will not compile new code if it reaches this limit.

opcache.jit_max_side_tracesint

Maximum number of side traces a root trace may have. The side trace is another execution flow that does not follow the path of compiled root trace. Side traces belonging to the same root trace will not be compiled if it reaches this limit.

opcache.jit_max_exit_countersint

Maximum number of side trace exit counters. This limits the total number of side traces there may be, across all root traces.

opcache.jit_hot_loopint

After how many iterations a loop is considered hot. Valid value range is[0,255]; for any setting out of this range, e.g., -1 or 256, default value will be used instead. Specially, a zero value will disable JIT to trace and compile any loops.

opcache.jit_hot_funcint

After how many calls a function is considered hot. Valid value range is[0,255]; for any setting out of this range, e.g., -1 or 256, default value will be used instead. Specially, a zero value will disable JIT to trace and compile any functions.

opcache.jit_hot_returnint

After how many returns a return is considered hot. Valid value range is[0,255]; for any setting out of this range, e.g., -1 or 256, default value will be used instead. Specially, a zero value will disable JIT to trace and compile any returns.

opcache.jit_hot_side_exitint

After how many exits a side exit is considered hot. Valid value range is[0,255]; for any setting out of this range, e.g., -1 or 256, default value will be used instead. Specially, a zero value will disable JIT to trace and compile any side exits.

opcache.jit_blacklist_root_traceint

Maximum number of times the compilation of a root trace is attempted before it is blacklisted.

opcache.jit_blacklist_side_traceint

Maximum number of times the compilation of a side trace is attempted before it is blacklisted.

opcache.jit_max_loop_unrollsint

Maximum number of attempts to unroll a loop in a side trace, trying to reach the root trace and close the outer loop.

opcache.jit_max_recursive_callsint

Maximum number of unrolled recursive call loops.

opcache.jit_max_recursive_returnsint

Maximum number of unrolled recursive return loops.

opcache.jit_max_polymorphic_callsint

Maximum number of attempts to inline polymorphic (dynamic or method) calls. Calls above this limit are treated as megamorphic and are not inlined.



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Preloading

As of PHP 7.4.0, PHP can be configured to preload scripts into the opcache when the engine starts. Any symbols (functions, classes, etc.) in those files will then become globally available for all requests without needing to be explicitly included. That trades convenience and performance (because the code is always available) for baseline memory usage. It also requires restarting the PHP process to clear pre-loaded scripts, meaning this feature is only practical to use in production, not in a development environment.

Note that the optimal tradeoff between performance and memory may vary with the application. "Preload everything" may be the easiest strategy, but not necessarily the best strategy. Additionally, preloading is only useful when there is a persistent process from one request to another. That means while it can work in a CLI script if the opcache is enabled, it's generally pointless. The exception is when using preloading onFFI libraries.

Nota:

Preloading is not supported on Windows.

Configuring preloading involves two steps, and requires that the opcache be enabled. First, set theopcache.preloadvalue inphp.ini:

opcache.preload=preload.php

preload.phpis an arbitrary file that will run once at server startup (PHP-FPM, mod_php, etc.) and load code into persistent memory. If PHP will be run as root (not recommended), theopcache.preload_uservalue can specify an alternate system user to run the preloading. Running preloading as root is not allowed.

In thepreload.phpscript, any file referenced byinclude,include_once,require,require_once, oropcache_compile_file()will be parsed into persistent memory. In the following example, all.phpfiles in thesrcdirectory will be preloaded, unless they are aTestfile.

<?php
$directory
= newRecursiveDirectoryIterator(__DIR__.'/src');
$fullTree= newRecursiveIteratorIterator($directory);
$phpFiles= newRegexIterator($fullTree,'/.+((?<!Test)+\.php$)/i',RecursiveRegexIterator::GET_MATCH);

foreach (
$phpFilesas$key=>$file) {
require_once(
$file[0]);
}
?>

Bothincludeandopcache_compile_file()will work, but have different implications for how code gets handled.

  • includewill execute code in the file, whileopcache_compile_file()will not. That means only the former supports conditional declaration (functions declared inside an if-block).
  • Becauseincludewill execute code, nestedincluded files will also be parsed and their declarations preloaded.
  • opcache_compile_file()can load files in any order. That is, ifa.phpdefines classAandb.phpdefines classBthat extendsA, thenopcache_compile_file()can load those two files in any order. When usinginclude, however,a.phpmustbe included first.
  • In either case, if a later script includes a file that has already been preloaded then its contents will still execute, but any symbols it defines will not be re-defined. Usinginclude_oncewill not prevent the file from being included a second time.
Which approach is better therefore depends on the desired behavior. With code that would otherwise use an autoloader,opcache_compile_file()allows for greater flexibility. With code that would otherwise be loaded manually,includewill be more robust.



Funciones de OPcache


opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_fileCompiles and caches a PHP script without executing it

Descripción

opcache_compile_file(string$filename):bool

This function compiles a PHP script and adds it to the opcode cache without executing it. This can be used to prime the cache after a Web server restart by pre-caching files that will be included in later requests.

Parámetros

filename

The path to the PHP script to be compiled.

Valores devueltos

Returnstrueiffilenamewas compiled successfully ofalseen caso de error.

Errores/Excepciones

Iffilenamecannot be loaded or compiled, an error of levelE_WARNINGis generated. You may use@to suppress this warning.

Ver también



opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configurationGet configuration information about the cache

Descripción

opcache_get_configuration():array|false

This function returns configuration information about the cache instance

Valores devueltos

Returns an array of information, including ini, blacklist and version

Errores/Excepciones

Ifopcache.restrict_apiis in use and the current path is in violation of the rule, an E_WARNING will be raised; no status information will be returned.

Ver también



opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_statusGet status information about the cache

Descripción

opcache_get_status(bool$include_scripts=true):array|false

This function returns state information about the cache instance

Parámetros

include_scripts

Include script specific state information

Valores devueltos

Returns an array of information, optionally containing script specific state information, ofalseen caso de error.

Errores/Excepciones

Ifopcache.restrict_apiis in use and the current path is in violation of the rule, an E_WARNING will be raised; no status information will be returned.

Ver también



opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidateInvalidates a cached script

Descripción

opcache_invalidate(string$filename,bool$force=false):bool

This function invalidates a particular script from the opcode cache. Ifforceis unset orfalse, the script will only be invalidated if the modification time of the script is newer than the cached opcodes.

Parámetros

filename

The path to the script being invalidated.

force

If set totrue, the script will be invalidated regardless of whether invalidation is necessary.

Valores devueltos

Returnstrueif the opcode cache forfilenamewas invalidated or if there was nothing to invalidate, orfalseif the opcode cache is disabled.

Ver también



opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cachedTells whether a script is cached in OPCache

Descripción

opcache_is_script_cached(string$filename):bool

This function checks if a PHP script has been cached in OPCache. This can be used to more easily detect the "warming" of the cache for a particular script.

Parámetros

filename

The path to the PHP script to be checked.

Valores devueltos

Returnstrueiffilenameis cached in OPCache,falseotherwise.

Ver también



opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_resetResets the contents of the opcode cache

Descripción

opcache_reset():bool

This function resets the entire opcode cache. After callingopcache_reset(), all scripts will be reloaded and reparsed the next time they are hit.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returnstrueif the opcode cache was reset, orfalseif the opcode cache is disabled.

Ver también


Tabla de contenidos




Control del búfer de salida


Introducción

Las funciones del Control de la salida permiten controlar cuándo la salida se evía desde un script. Esto puede ser útil en diferentes situaciones, especialmente si es necesario enviar cabeceras al navegador después de que el script haya comenzado a producir datos. Las funciones del Control de la salida no afectan a las cabeceras enviadas usandoheader()osetcookie(), solamente a las funciones comoechoy a los datos entre bloques de código de PHP.

Nota:

Cuando se actualiza desde PHP 4.1.x (y 4.2.x) a 4.3.x, debido a un error en versones anteriores, ha de asegurarse de queimplicit_flushesté enOFFen el ficherophp.ini, de lo contrario cualquier cosa producida conob_start()no se ocultará desde la salida.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

No se requiere de ninguna instalación para utilizar estas funciones; forman parte del núcleo de PHP.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Opciones de configuración del Control de la salida
NombrePor defectoCambiableHistorial de cambios
output_buffering"0"PHP_INI_PERDIR 
output_handlerNULLPHP_INI_PERDIRDisponible desde PHP 4.0.4.
implicit_flush"0"PHP_INI_ALLPHP_INI_PERDIR en PHP <= 4.2.3.
url_rewriter.tags"a=href,area=href,frame=src,form=,fieldset="PHP_INI_ALLDisponible desde PHP 4.0.4. Antes de PHP 7.1.0, se usaba para establecer reescriburas de trans sid de sesión. Desde 7.1.0 solamente lo utililzaoutput_add_rewrite_var().
url_rewriter.hosts$_SERVER['HTTP_HOST']is used as default.PHP_INI_ALLDisponible desde PHP 7.1.0
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

output_bufferingboolean/integer

Se puede habilitar el búfer de salida para todos los ficheros estableciendo esta directiva a 'On'. Si se necesita limitar el tamaño del búfer a un tamaño en particular, se puede usar un número máximo de bytes en lugar de 'On' como valor para esta directiva (p.ej., output_buffering=4096). A partir de PHP 4.3.5, esta direcitva siempre es 'Off' en PHP-CLI.

output_handlerstring

Se pueden redireccionar todas las salidas producidas por los scripts a una funcion. Por ejemplo, si se establece output_handler amb_output_handler(), la codificación de caracteres será convertida de forma transparente a la codificación especificada. Al establecer cualquier gestor de salida automáticamente se activará el búfer de salida.

Nota:

No se puede usarmb_output_handler()conob_iconv_handler(), y tampoco se puedem usar juntosob_gzhandler()yzlib.output_compression.

Nota:

Solamente se pueden usar funciones internas con esta directiva. Para funciones definidas por el usuario se ha de usarob_start().

implicit_flushboolean

Esfalsede forma predeterminada. Cambiarla atruele dirá a PHP que indique a la capa de salida que se vuelque a sí misma automáticamente después de cada bloque de salida. Esto es equivalente a llamar a la función de PHPflush()después de cada llamada aprintoechoy de cada bloque deHTML.

Cuando se usa PHP dentro de un entorno web, la activación de esta opción tiene serias implicaciones de rendimiento, por lo que solamente se recomienda para propósitos de depuración. Este valor estruede forma predeterminada cuando se opera bajo laSAPI CLI.

Véase tambiénob_implicit_flush().

url_rewriter.tagsstring
url_rewriter.tagsespecifica qué etiquetas HTML son reescritas por valores deoutput_add_rewrite_var(). Las predeterminadas sona=href,area=href,frame=src,input=src,form=formes una etiqueta especial.<input hidden="id_sesión" name="nombre_sesión">se añade como variable de formulario.

Nota:Antes de PHP 7.1.0,url_rewriter.tagsse utilizaba para especificarsession.trans_sid_tags. Desde PHP 7.1.0,fieldsetya no se considera una etiqueta especial.

url_rewriter.hostsstring
url_rewriter.hostsespecifica los 'hosts' que son reescritos para incluir valores deoutput_add_rewrite_var(). El predeterminado es$_SERVER['HTTP_HOST']. Se pueden especificar varios hosts mediante ",", y no se permiten espacios entre hosts. P.ej.php.net,wiki.php.net,bugs.php.net



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Estas constantes están disponibles siempre ya que forman parte del núcleo de PHP.

PHP_OUTPUT_HANDLER_START(integer)

Indica que el almacenamiento en el búfer de salida ha comenzado.

PHP_OUTPUT_HANDLER_WRITE(integer)

Indica que el búfer de salida está siendo volcado y tiene datos para producir una salida.

Disponible desde PHP 5.4.

PHP_OUTPUT_HANDLER_FLUSH(integer)

Indica que el búfer de salida ha sido volcado.

Disponible desde PHP 5.4.

PHP_OUTPUT_HANDLER_CLEAN(integer)

Indica que el búfer de salida ha sido limpiado.

Disponible desde PHP 5.4.

PHP_OUTPUT_HANDLER_FINAL(integer)

Indica que esta es la operación final del almacenamiento del búfer de salida.

Disponible desde PHP 5.4.

PHP_OUTPUT_HANDLER_CONT(integer)

Indica que el búfer de salida ha sido volcado, pero que el almacenamiento en el búfer de salida continurá.

A partir de PHP 5.4, esta constante es un alias dePHP_OUTPUT_HANDLER_WRITE.

PHP_OUTPUT_HANDLER_END(integer)

Indica que el almacenamiento del búfer de salida ha finalizado.

A partir de PHP 5.4, esta constante es un alias dePHP_OUTPUT_HANDLER_FINAL.

PHP_OUTPUT_HANDLER_CLEANABLE(integer)

Controla si un búfer de salida creado porob_start()puede ser limpiado.

Disponible desde PHP 5.4.

PHP_OUTPUT_HANDLER_FLUSHABLE(integer)

Controla si un búfer de salida creado porob_start()puede ser volcado.

Disponible desde PHP 5.4.

PHP_OUTPUT_HANDLER_REMOVABLE(integer)

Controla si un búfer de salida creado porob_start()puede ser eliminado antes de finalizar el script.

Disponible desde PHP 5.4.

PHP_OUTPUT_HANDLER_STDFLAGS(integer)

El conjunto predeterminado de banderas de búfer de salida; actualmente equivalente aPHP_OUTPUT_HANDLER_CLEANABLE|PHP_OUTPUT_HANDLER_FLUSHABLE|PHP_OUTPUT_HANDLER_REMOVABLE.

Disponible desde PHP 5.4.



Ejemplos

Tabla de contenidos


Uso básico

Ejemplo #1 Ejemplo de control de la salida

<?php

ob_start
();
echo
"Hola\n";

setcookie("nombre_cookie","datos_cookie");

ob_end_flush();

?>

En el ejemplo anterior, la salida deechosería almacenada en el búfer de salida hasta que se llamara aob_end_flush(). Mientras tanto, la llamada asetcookie()almacenaría con éxito una cookie sin causar ningún error. (Las cabeceras normalmente no se pueden enviar al navegador después de haber enviado ya los datos.)




Funciones del Control de la salida

Ver también

Véase tambiénheader()ysetcookie().


flush

(PHP 4, PHP 5, PHP 7, PHP 8)

flushVaciar el búfer de salida del sistema

Descripción

flush():void

Vacía los búferes de escritura del sistema de PHP y de cualquiera que sea el backend en el que se esté usando PHP (CGI, un servidor web, etc.). Trata de enviar toda la salida producida hasta el momento al navegador, aunque se ha de tener en cuenta algunas cosas.

flush()podría no sobreescribir el esquema del almacenamiento en búfer del servidor web, por lo que no tiene efecto sobre ningún búfer en el lado del cliente del navegador. Tampoco afecta al mecanismo del búfer de salida del espacio de usuario de PHP. Esto significa que se ha de llamar tanto aob_flush()como aflush()para volcar los búferes de salida si se están usando aquellos.

Algunos servidores, especialmente en Win32, seguirán almacenando en búfer la salida producida por un script hasta que éste termine antes de transmitir los resultados al navegador.

Puede que algunos módulos de servidor para Apache, como mod_gzip, usen búferes propios que causarán queflush()no resulte en un envío inmediato de los datos al cliente.

Incluso el navegador puede almacenar en búfer su entrada antes de mostrarla. Netscape, por ejemplo, almacena en búfer el texto hasta que recibe un final de línea o el comienzo de una etiqueta, por lo que no interpretará las tablas hasta que se encuentre la etiqueta </table> de la tabla más externa.

Algunas versiones de Microsoft Internet Explorer solo empezarán a mostrar la página después de que han recibido 256 bytes de salida, por lo que puede que sea necesario enviar espacios en blanco extra antes del volcado para que se muestre la página en tales navegadores.

Valores devueltos

No devuelve ningún valor.

Ver también

  • ob_flush()- Vaciar (enviar) el búfer de salida
  • ob_clean()- Limpiar (eliminar) el búfer de salida
  • ob_end_flush()- Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_end_clean()- Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo



ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_cleanLimpiar (eliminar) el búfer de salida

Descripción

ob_clean():void

Esta función desecha el contenido del búfer de salida.

Esta función no destruye el búfer de salida como lo haceob_end_clean().

El búfer de salida debe estar iniciado porob_start()con el indicadorPHP_OUTPUT_HANDLER_CLEANABLE. Si no,ob_clean()no funcionará.

Valores devueltos

No devuelve ningún valor.

Ver también

  • ob_flush()- Vaciar (enviar) el búfer de salida
  • ob_end_flush()- Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_end_clean()- Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo



ob_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_cleanLimpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo

Descripción

ob_end_clean():bool

Esta función desecha el contenido del búfer de salida en cola y lo desactiva. Si fuera necesario continuar procesando el contenido del búfer, se ha de llamar aob_get_contents()antes que aob_end_clean(), ya que el contenido del búfer es desechado cuando se llama aob_end_clean().

El búfer de salida debe estar iniciado porob_start()con los indicadoresPHP_OUTPUT_HANDLER_CLEANABLEyPHP_OUTPUT_HANDLER_REMOVABLE. Si no,ob_end_clean()no funcionará.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error. Entre las posibles razones de un fallo se encuentra llamar a la función sin un búfer activo, o que por algún motivo no se pueda eliminar un búfer (posible en el caso de búferes especiales).

Errores/Excepciones

Si la función falla, genera un error de nivelE_NOTICE.

Ejemplos

El siguiente ejemplo muestra una forma sencilla de deshacerse de todos los búferes de salida:

Ejemplo #1 Ejemplo deob_end_clean()

<?php
ob_start
();
echo
'Texto que no será mostrado.';
ob_end_clean();
?>

Ver también



ob_end_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flushVolcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo

Descripción

ob_end_flush():bool

Esta función enviará el contenido del búfer de salida en cola (si existe) y los deshabilitará. Si fuera necesario procesar el contenido del búfer, se ha de llamar aob_get_contents()antes que aob_end_flush(), ya que el contenido del búfer es descartado después de llamar aob_end_flush().

El búfer de salida debe estar iniciado porob_start()con los indicadoresPHP_OUTPUT_HANDLER_FLUSHABLEyPHP_OUTPUT_HANDLER_REMOVABLESi no,ob_end_flush()no funcionará.

Nota:Esta función es similar aob_get_flush(), excepto queob_get_flush()devuelve el búfer como una cadena de caracteres.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error. Entre las posibles razones de un fallo se encuentra llamar a la función sin un búfer activo, o que por algún motivo no se pueda eliminar un búfer (posible en el caso de búferes especiales).

Errores/Excepciones

Si la función falla, genera un error de nivelE_NOTICE.

Ejemplos

Ejemplo #1 Ejemplo deob_end_flush()

El siguiente ejemplo muestra una forma sencilla de volcar y finalizar todos los búferes de salida:

<?php
while (@ob_end_flush());
?>

Ver también

  • ob_start()- Activa el almacenamiento en búfer de la salida
  • ob_get_contents()- Devolver el contenido del búfer de salida
  • ob_get_flush()- Volcar el búfer de salida, devolverlo como una cadena de caracteres y deshabilitar el almacenamiento en el búfer de salida
  • ob_flush()- Vaciar (enviar) el búfer de salida
  • ob_end_clean()- Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo



ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flushVaciar (enviar) el búfer de salida

Descripción

ob_flush():void

Esta función enviará el contenido del búfer de salida (si existe). Si fuera necesario continuar procesando el contenido del búfer, se ha de llamar aob_get_contents()antes que aob_flush(), ya que el contenido del búfer es descartado después de llamar aob_flush().

Esta función no destruye el búfer de salida, como lo haceob_end_flush().

Valores devueltos

No devuelve ningún valor.

Ver también

  • ob_get_contents()- Devolver el contenido del búfer de salida
  • ob_clean()- Limpiar (eliminar) el búfer de salida
  • ob_end_flush()- Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_end_clean()- Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo



ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_cleanObtiene el contenido del búfer actual y elimina el búfer de salida actual

Descripción

ob_get_clean():string

Obtiene el contenido del búfer actual y elimina el búfer de salida actual.

ob_get_clean()básicamente ejecutaob_get_contents()yob_end_clean().

El búfer de salida debe estar iniciado porob_start()con el indicadorPHP_OUTPUT_HANDLER_CLEANABLESi no,ob_get_clean()no funcionará.

Valores devueltos

Devuelve el contenido del búfer de salida y finaliza el almacenamiento en el mismo. Si el almacenamiento en el búfer de salida no está activo, entonces devuelvefalse.

Ejemplos

Ejemplo #1 Un ejemplo sencillo deob_get_clean()

<?php

ob_start
();

echo
"Hola Mundo";

$salida=ob_get_clean();
$salida=strtolower($salida);

var_dump($salida);
?>

El resultado del ejemplo sería:


string(10) "hola mundo"

Ver también



ob_get_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contentsDevolver el contenido del búfer de salida

Descripción

ob_get_contents():string

Obtiene el contenido del búfer de salida, sin borrarlo.

Valores devueltos

Devolverá el contenido del búfer de salida, ofalsesi el almacenameinto en el búfer de salida no está activo.

Ejemplos

Ejemplo #1 Un ejemplo sencillo deob_get_contents()

<?php

ob_start
();

echo
"Hola ";

$salida1=ob_get_contents();

echo
"Mundo";

$salida2=ob_get_contents();

ob_end_clean();

var_dump($salida1,$salida2);
?>

El resultado del ejemplo sería:

string(5) "Hola "
string(10) "Hola Mundo"

Ver también



ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flushVolcar el búfer de salida, devolverlo como una cadena de caracteres y deshabilitar el almacenamiento en el búfer de salida

Descripción

ob_get_flush():string

ob_get_flush()vuelca el búfer de salida, lo devuelve como una cadena de caracteres y deshabilita el almacenamiento en el búfer de salida.

El búfer de salida debe estar iniciado porob_start()con el indicadorPHP_OUTPUT_HANDLER_FLUSHABLESi no,ob_get_flush()no funcionará.

Nota:Esta función es similar aob_end_flush(), excepto que esta función además devuelve el búfer como una cadena de caracteres.

Valores devueltos

Devuelve el búfer de salida, ofalsesi el almacenamiento en el búfer no está activo.

Ejemplos

Ejemplo #1 Ejemplo deob_get_flush()

<?php
//usar output_buffering=On
print_r(ob_list_handlers());

//guardar el búfer en un fichero
$búfer=ob_get_flush();
file_put_contents('bufer.txt',$búfer);

print_r(ob_list_handlers());
?>

El resultado del ejemplo sería:

Array
(
    [0] => default output handler
)
Array
(
)

Ver también

  • ob_end_clean()- Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_end_flush()- Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_list_handlers()- Enumerar todos los gestores de salida en uso



ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_lengthDevolver la longitud del búfer de salida

Descripción

ob_get_length():int

Esta función devolverá la longitud del contenido del búfer de salida, en bytes.

Valores devueltos

Devuelve la longitud del contenido del búfer de salida, en bytes, ofalsesi no está activo el almacenamiento en búfer.

Ejemplos

Ejemplo #1 Un ejemplo sencillo deob_get_length()

<?php

ob_start
();

echo
"Hola ";

$longitud1=ob_get_length();

echo
"Mundo";

$longitud2=ob_get_length();

ob_end_clean();

echo
$longitud1.", .".$longitud2;
?>

El resultado del ejemplo sería:

5, 10

Ver también



ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_levelDevolver el nivel de anidamiento del mecanismo de almacenamiento en el búfer de salida

Descripción

ob_get_level():int

Devuelve el nivel de anidamiento del mecanismo de almacenamiento en el búfer de salida.

Valores devueltos

Devuelve el nivel de los gestores de almacenamiento en búfer de salida anidados, o cero si el almacenamiento en búfer no está activo.

Ver también



ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_statusObtener el estado de los búferes de salida

Descripción

ob_get_status(bool$full_status= FALSE):array

ob_get_status()devuelve la información de estado sobre el búfer de salida de nivel superior, o sobre todos los niveles activos de búferes de salida sifull_statuses establecido atrue.

Parámetros

full_status

truepara devolver todos los niveles de búferes de salida activos. Si esfalseo no se establece, solo es devuelto el búfer de salida de nivel más alto.

Valores devueltos

Si esta función es llamada sin el parámetrofull_status, o confull_status=false, se devuelve un único array con los siguientes elementos:

Array
(
    [level] => 2
    [type] => 0
    [status] => 0
    [name] => URL-Rewriter
    [del] => 1
)
Resultados simples deob_get_status()
ClaveValor
levelNivel de anidamiento de la salida
typePHP_OUTPUT_HANDLER_INTERNAL(0)oPHP_OUTPUT_HANDLER_USER (1)
statusUn valor entrePHP_OUTPUT_HANDLER_START(0),PHP_OUTPUT_HANDLER_CONT(1) oPHP_OUTPUT_HANDLER_END(2)
nameNombre del gestor de salida activo, o 'default output handler' si no hay uno establecido
delBandera de borrado, tal y como está establecido porob_start()

Si se llama confull_status=true, se devuelve un array con un elemento por cada nivel de búfer de salida activo. El nivel de salida se usa como la clave del array de nivel superior, y cada elemento del array en sí es otro array que contiene información de estado sobre un nivel de salida activo.

Array
(
    [0] => Array
        (
            [chunk_size] => 0
            [size] => 40960
            [block_size] => 10240
            [type] => 1
            [status] => 0
            [name] => default output handler
            [del] => 1
        )

    [1] => Array
        (
            [chunk_size] => 0
            [size] => 40960
            [block_size] => 10240
            [type] => 0
            [buffer_size] => 0
            [status] => 0
            [name] => URL-Rewriter
            [del] => 1
        )

)

La salida completa contiene los siguientes elementos adicionales:

Resultados completos deob_get_status()
ClaveValor
chunk_sizeTamaño del segmento, tal y como es establecido porob_start()
size...
blocksize...

Ver también

  • ob_get_level()- Devolver el nivel de anidamiento del mecanismo de almacenamiento en el búfer de salida
  • ob_list_handlers()- Enumerar todos los gestores de salida en uso



ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandlerFunción de llamada de retorno de ob_start para comprimir el búfer de salida con gzip

Descripción

ob_gzhandler(string$buffer,int$mode):string

ob_gzhandler()tiene por objeto usarse como una función de llamada de retorno paraob_start()para facilitar en envío de datos codificados con gz a los navegadores web que admiten la compresión de páginas web. Antes de queob_gzhandler()realmente envíe datos comprimidos, determina el tipo de codificación de contenido que aceptará el navegador ("gzip", "deflate" o ninguno) y devolverá su salida en consecuencia. Se admiten todos los navegadores, ya que es responsabilidad de los mismos enviar la cabecera correcta que indique que acepta páginas web comprimidas. Si un navegador no admite páginas comprimidas, esta función devolveráfalse.

Parámetros

buffer

mode

Valores devueltos

Ejemplos

Ejemplo #1 Ejemplo deob_gzhandler()

<?php

ob_start
("ob_gzhandler");

?>
<html>
<body>
<p>Esta debería ser una página comprimida.</p>
</body>
</html>

Notas

Nota:

ob_gzhandler()requiere la extensiónzlib.

Nota:

No se pueden usar juntosob_gzhandler()yzlib.output_compression. Observe también que se prefiere el uso dezlib.output_compressionantes queob_gzhandler().

Ver también

  • ob_start()- Activa el almacenamiento en búfer de la salida
  • ob_end_flush()- Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo



ob_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flushHabilitar/deshabilitar el volcado implícito

Descripción

ob_implicit_flush(int$flag= true):void

ob_implicit_flush()habilitará o deshabilitará el volcado implícito. El volcado implícito resultará en una operación de volcado después de cada llamada que produzca salida, de modo que no son necesarias las llamadas explícitas aflush().

Parámetros

flag

truepara habilitar el volcado implícito,falsepara deshabilitarlo.

Valores devueltos

No devuelve ningún valor.

Ver también

  • flush()- Vaciar el búfer de salida del sistema
  • ob_start()- Activa el almacenamiento en búfer de la salida
  • ob_end_flush()- Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo



ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlersEnumerar todos los gestores de salida en uso

Descripción

ob_list_handlers():array

Enumera todos los gestores de salida en uso.

Valores devueltos

Esta función devolverá un array con los gestores de salida en uso (si existen). Sioutput_bufferingestá habilitado o se usó una función anónima conob_start(),ob_list_handlers()devolverá "default output handler" (gestor de salida predeterminado).

Ejemplos

Ejemplo #1 Ejemplo deob_list_handlers()

<?php
//usando output_buffering=On
print_r(ob_list_handlers());
ob_end_flush();

ob_start("ob_gzhandler");
print_r(ob_list_handlers());
ob_end_flush();

// funciones anónimas
ob_start(function($string) { return$string; });
print_r(ob_list_handlers());
ob_end_flush();
?>

El resultado del ejemplo sería:

Array
(
    [0] => default output handler
)

Array
(
    [0] => ob_gzhandler
)

Array
(
    [0] => Closure::__invoke
)

Ver también

  • ob_end_clean()- Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_end_flush()- Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_get_flush()- Volcar el búfer de salida, devolverlo como una cadena de caracteres y deshabilitar el almacenamiento en el búfer de salida
  • ob_start()- Activa el almacenamiento en búfer de la salida



ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_startActiva el almacenamiento en búfer de la salida

Descripción

ob_start(callable$output_callback=null,int$chunk_size= 0,int$flags=PHP_OUTPUT_HANDLER_STDFLAGS):bool

Esta función activará el almacenamiento en búfer de la salida. Mientras dicho almacenamiento esté activo, no se enviará ninguna salida desde el script (aparte de cabeceras); en su lugar la salida se almacenará en un búfer interno.

El contenido de este búfer interno se puede copiar a una variable de tipo string usandoob_get_contents(). Para producir la salida de lo almacenado en el búfer interno se ha de usarob_end_flush(). De forma alternativa,ob_end_clean()desechará de manera silenciosa el contenido del búfer.

Advertencia

Algunos servidores web (p.ej. Apache) cambian en directorio de trabajo de un script cuando se invoca a la función de llamada de retorno. Se puede cambiar de nuevo mediante, por ejemplo,chdir(dirname($_SERVER['SCRIPT_FILENAME']))en la función de llamada de retorno.

Los búferes de salida son apilables, es decir, que se podría llamar aob_start()mientras otroob_start()esté activo. Se ha de asegurar llamar aob_end_flush()las veces apropiadas. Si están activas múltiples funciones de llamada de retorno de salida, la salida se filtrará secuencialmente por cada una de ellas en orden de anidamiento.

Parámetros

output_callback

Se puede especificar una funciónoutput_callbackopcional. Esta función toma un string como parámetro y debería devolver otro string. La función se llamará cuando el búfer de salida sea volcado (enviado), limpiado (conob_flush(),ob_clean()o alguna función similar) o cuando el búfer de salida sea volcado al navegador al final de la petición. Cuando se llame aoutput_callback, ésta recibirá el contenido del búfer de salida como su propio parámetro, y se espera que devuelva un nuevo búfer de salida como resultado, que será enviado al navegador. Sioutput_callbackno es una función llamable, esta función devolveráfalse. Esta es la firma de la llamada de retorno:

handler(string$buffer,int$phase= ?):string
buffer
Contenido del búfer de salida.
phase
Máscara de bits de constantesPHP_OUTPUT_HANDLER_*.

Sioutput_callbackdevuelvefalse, se enviará la entrada original al navegador.

El parámetrooutput_callbackse puede omitir pasando un valornull.

ob_end_clean(),ob_end_flush(),ob_clean(),ob_flush()yob_start()no se pueden llamar desde una función de llamada de retorno. Si se hace, el comportamiento no estará definido. Si se quiere borrar el contenido de un búfer, se ha de devolver "" (un string nulo) desde la función de llamada de retorno. Tampoco se pueden llamar a funciones usando las funciones de búfer de salida comoprint_r($expresión, true)ohighlight_file($nombre_fichero, true)desde una función de llamada de retorno.

Nota:

En PHP 4.0.4,ob_gzhandler()se introdujo para facilitar el envío de datos codificados con gz a los navegadores web que admitan páginas web comprimidas.ob_gzhandler()determima el tipo de codificación de contenido que aceptará el navegador y devolverá su salida en consecuencia.

chunk_size

Si se proporciona el parámetro opcionalchunk_size, el búffer será volcado después de cualquier llamada de salida que cause que la longitud del búfer sea igual o exceda achunk_size. El valor predeterminado0significa que la función de salida será llamada únicamente cuando el búfer de salida se cierre.

Antes de PHP 5.4.0, el valor1era un caso especial que establecía el tamaño de segmento a 4096 bytes.

flags

El parámetroflagses una máscara de bits que controla las operaciones que se pueden realizar sobre el búfer de salida. Lo predeterminado es permitir que los búferes de salida sean limpiados, volcados y borrados, lo que se puede hacer explícitamente mediantePHP_OUTPUT_HANDLER_CLEANABLE|PHP_OUTPUT_HANDLER_FLUSHABLE|PHP_OUTPUT_HANDLER_REMOVABLE, oPHP_OUTPUT_HANDLER_STDFLAGScomo clave.

Cada bandera (flag) controla el acceso a un conjunto de funciones, como está descrito a continuación:

ConstanteFunciones
PHP_OUTPUT_HANDLER_CLEANABLEob_clean(),ob_end_clean(), yob_get_clean().
PHP_OUTPUT_HANDLER_FLUSHABLEob_end_flush(),ob_flush(), yob_get_flush().
PHP_OUTPUT_HANDLER_REMOVABLEob_end_clean(),ob_end_flush(), yob_get_flush().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
7.0.0En caso de utilizarob_start()dentro de una retrollamada del búfer de salida, esta función ya no emitirá unE_ERROR, si no unE_RECOVERABLE_ERROR, permitiendo a los manejadores de errores propios capturar tales errores.
5.4.0El tercer parámetro deob_start()se cambió de un parámetrobooleanllamadoerase(el cual, si se establecía afalse, prevenía al búfer de salida de ser eliminado hasta el final de la ejecución del script) a un parámetrointegerllamadoflags. Desafortunadamente, esto resulta en una rotura de compatibilidad de la API para código escrito antes de PHP 5.4.0 que use el tercer parámetro. Véaseel ejemplo de banderaspara saber cómo manejar esto con código que necesite ser compatible con ambas.
5.4.0Un tamaño de segmento de1ahora resulta en segmentos de 1 byte que se van a enviar al búfer de salida.
4.3.2Se modficó esta función que devuelvafalseen caso de que la funciónoutput_callbackpasada no pueda ejecutarse.

Ejemplos

Ejemplo #1 Ejemplo de una función de llamada de retorno definida por el usuario

<?php

functioncallback($búfer)
{
// reemplazar todas las manzanas por naranjas
return (str_replace("manzanas","naranjas",$búfer));
}

ob_start("callback");

?>
<html>
<body>
<p>Es como comparar manzanas con naranjas.</p>
</body>
</html>
<?php

ob_end_flush
();

?>

El resultado del ejemplo sería:

<html>
<body>
<p>Es como comparar naranjas con naranjas.</p>
</body>
</html>

Ejemplo #2 Crear un búfer de salida imborrable de forma compatible con PHP 5.3 y 5.4

<?php

if (version_compare(PHP_VERSION,'5.4.0','>=')) {
ob_start(null,0,PHP_OUTPUT_HANDLER_STDFLAGS^
PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
ob_start(null,0,false);
}

?>

Ver también

  • ob_get_contents()- Devolver el contenido del búfer de salida
  • ob_end_clean()- Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_end_flush()- Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_implicit_flush()- Habilitar/deshabilitar el volcado implícito
  • ob_gzhandler()- Función de llamada de retorno de ob_start para comprimir el búfer de salida con gzip
  • ob_iconv_handler()- Convierte la codificación de caracteres al manejador del buffer de salida
  • mb_output_handler()- Función de llamada de retorno que convierte la codificación de caracteres en búfer de salida
  • ob_tidyhandler()- Función callback de ob_start para reparar el buffer



output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_varAñadir valores al mecanismo de reescritura de URLs

Descripción

output_add_rewrite_var(string$name,string$value):bool

Esta función añade otro par nombre/valor al mecanismo de reescritura de URLs. El nombre y el valor se agregarán a los URLs (como parámetros de GET) y a los formularios (como camos intput ocultos) de la misma forma que el ID de sesión cuando la reescritura de URLs de forma transparente está habilitada consession.use_trans_sid. Observe que los URLs absolutos (http://example.com/..) no son reescritos.

El comportamiento de esta función está controlado por el parámetrourl_rewriter.tagsdephp.ini.

Nota:Al llamar a esta función se iniciará el almacenamiento implícito en búfer de salida si no estaba ya activo.

Parámetros

name

El nombre de la variable.

value

El valor de la variable.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deoutput_add_rewrite_var()

<?php
output_add_rewrite_var
('var','valor');

// algunos enlaces
echo'<a href="fichero.php">enlace</a>
<a href="http://example.com">enlace2</a>'
;

// un formulario
echo'<form action="script.php" method="post">
<input type="text" name="var2" />
</form>'
;

print_r(ob_list_handlers());
?>

El resultado del ejemplo sería:

<a href="fichero.php?var=valor">enlace</a>
<a href="http://example.com">enlace2</a>

<form action="script.php" method="post">
<input type="hidden" name="var" value="valor" />
<input type="text" name="var2" />
</form>

Array
(
    [0] => URL-Rewriter
)

Ver también



output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_varsRestablecer los valores del mecanismo de reescritura de URLs

Descripción

output_reset_rewrite_vars():bool

Esta función restablece el mecanismo de reescritura de URLs y elimina todas las variables de reescritura establecidas previamente por la funciónoutput_add_rewrite_var().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
7.1.0Antes de PHP 7.1.0, la variables reescritas poroutput_add_rewrite_var()utilizaban el mismo buffer de salida del módulo de sesión trans sid. Desde PHP 7.1.0, se usa un buffer de salida dedicado youtput_reset_rewrite_vars()solo elimina las variables reescritas definidas poroutput_add_rewrite_var().

Ejemplos

Ejemplo #1 Ejemplo deoutput_reset_rewrite_vars()

<?php
session_start
();
output_add_rewrite_var('var','value');

echo
'<a href="file.php">link</a>';
ob_flush();

output_reset_rewrite_vars();
echo
'<a href="file.php">link</a>';
?>

El resultado del ejemplo sería:

<a href="file.php?PHPSESSID=xxx&var=value">link</a>
<a href="file.php">link</a>

Ver también


Tabla de contenidos

  • flush— Vaciar el búfer de salida del sistema
  • ob_clean— Limpiar (eliminar) el búfer de salida
  • ob_end_clean— Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_end_flush— Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
  • ob_flush— Vaciar (enviar) el búfer de salida
  • ob_get_clean— Obtiene el contenido del búfer actual y elimina el búfer de salida actual
  • ob_get_contents— Devolver el contenido del búfer de salida
  • ob_get_flush— Volcar el búfer de salida, devolverlo como una cadena de caracteres y deshabilitar el almacenamiento en el búfer de salida
  • ob_get_length— Devolver la longitud del búfer de salida
  • ob_get_level— Devolver el nivel de anidamiento del mecanismo de almacenamiento en el búfer de salida
  • ob_get_status— Obtener el estado de los búferes de salida
  • ob_gzhandler— Función de llamada de retorno de ob_start para comprimir el búfer de salida con gzip
  • ob_implicit_flush— Habilitar/deshabilitar el volcado implícito
  • ob_list_handlers— Enumerar todos los gestores de salida en uso
  • ob_start— Activa el almacenamiento en búfer de la salida
  • output_add_rewrite_var— Añadir valores al mecanismo de reescritura de URLs
  • output_reset_rewrite_vars— Restablecer los valores del mecanismo de reescritura de URLs



Opciones e Información de PHP


Introducción

Estas funciones permiten obtener mucha información sobre PHP, p.ej., configuración en tiempo de ejecución, extensiones en uso, versión, y mucho más. También se pueden encontrar funciones para establecer opciones al ejecutar PHP. Aquí se puede encontrar la función probablemente más conocida de PHP -phpinfo()-.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

No se requiere de ninguna instalación para utilizar estas funciones; forman parte del núcleo de PHP.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Opciones de configuración de opciones/información de PHP
NombrePor defectoCambiableHistorial de cambios
assert.active"1"PHP_INI_ALL 
assert.bail"0"PHP_INI_ALL 
assert.warning"1"PHP_INI_ALL 
assert.callbackNULLPHP_INI_ALL 
assert.quiet_eval"0"PHP_INI_ALL 
assert.exception"0"PHP_INI_ALLDisponible desde PHP 7.0.0.
enable_dl"1"PHP_INI_SYSTEMEsta característica obsoletaseráeliminadacon certeza en el futuro.
max_execution_time"30"PHP_INI_ALL 
max_input_time"-1"PHP_INI_PERDIRDisponible desde PHP 4.3.0.
max_input_nesting_level"64"PHP_INI_PERDIRDisponible desde PHP 4.4.8. y PHP 5.2.3.
max_input_vars1000PHP_INI_PERDIRAvailable since PHP 5.3.9.
magic_quotes_gpc"1"PHP_INI_PERDIRPHP_INI_ALL en PHP <= 4.2.3. Eliminado en PHP 5.4.0
magic_quotes_runtime"0"PHP_INI_ALLEliminado en PHP 5.4.0
zend.enable_gc"1"PHP_INI_ALLDisponible desde PHP 5.3.0.
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

assert.activeboolean

Activa la evaluación deaserciones().

assert.bailboolean

Terminar la ejecución del script si falla una aserción.

assert.warningboolean

Lanzar un PHP warning for cada aserción que falle.

assert.callbackstring

Función de usuario a llamar cuando fallen las aserciones.

assert.quiet_evalboolean

Usar la configuración actual deerror_reporting()durante las expresiones de evaluación de aserciones. Si está habilitado, no se mostrarán errores (incondicional error_reporting(0)) durante evaluación. Si está deshabitado, se mostrarán errores según la configuración deerror_reporting()

assert.exceptionboolean

Emite una excepciónAssertionErrorpara la afirmación fallida.

enable_dlboolean

Esta directiva es muy útil solamente en la versión PHP con el módulo Apache. Se puede activar o desactivar la carga dinámica de extensiones PHP condl()por servidor virtual o directorio.

La razón principal para desactivar la carga dinámica es por seguridad. Con la carga dinámica, es posible ignorar todas las restriccionesopen_basedir. De forma predeterminada se permite la carga dinámica.

max_execution_timeinteger

Este valor establece el tiempo máximo en segundos que se permite ejecutar antes de que el analizador termine. Esto ayuda a prevenir que scripts mal escritos bloqueen el servidor. El valor por defecto es30. Cuando se ejecuta PHP desde lalínea de comandosel valor por defecto es0.

El tiempo de ejecución máxima no está afectada por llamadas al sistema, operaciones de stream etc. Por favor véase la funciónset_time_limit()para más información.

El servidor web puede tener otras configuraciones de tiempo de espera que quizá interrumpan la ejecución de PHP. Apache tiene la directivaTimeouty IIS tiene la función CGI timeout. Las dos de 300 segundos por omisión. Véase la documentación del servidor web para información específica.

max_input_timeinteger

Establece el tiempo máximo en segundos que se permite a un script analizar datos de entrada, como POST y GET. La medición comienza en el momento en que PHP es invocado en el servidor y finaliza cuando la ejecución comienza.

max_input_nesting_levelinteger

Establece el máximo de profundidad de anidamiento paravariables de entrada(p.ej.$_GET,$_POST.)

max_input_varsinteger

Cuantasvariables de entradapueden ser aceptadas (el límite se aplica a los arrays superglobales $_GET, $_POST y $_COOKIE de forma separada). El uso de esta directiva mitiga la posibilidad de ataques de denegación de servicio que utilizan colisiones de hash. Si hay más variables de entrada que las especificadas por la presente directiva, unE_WARNINGes emitido, y otras variables entrada son truncadas a partir de la solicitud.

magic_quotes_gpcboolean
Advertencia

Esta característica ha sido declaradaOBSOLETAdesde PHP 5.3.0 yELIMINADAa partir de PHP 5.4.0.

Establece las magic_quotes state para operaciones GPC (Get/Post/Cookie). Cuando las magic_quotes están activadas, todas las ' (comillas simples), " (comillas dobles), \ (barra invertida) y NUL's son escapados con una barra invertida de forma automática..

Ver tambiénget_magic_quotes_gpc()

magic_quotes_runtimeboolean
Advertencia

Esta característica ha sido declaradaOBSOLETAdesde PHP 5.3.0 yELIMINADAa partir de PHP 5.4.0.

Simagic_quotes_runtimeestá activado, la mayoría de funciones que devuelven datos desde cualquier tipo de recurso externo incluyendo bases de datos y ficheros de texto contendrán comillas escapadas con barras invertidas.

Funciones afectadas pormagic_quotes_runtime(no incluye funciones de PECL):

zend.enable_gcboolean

Habilita o deshabilita el colector de referencia circular.



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Estas constantes están disponibles siempre ya que forman parte del núcleo de PHP.

Constantes predefinidas enphpcredits()
ConstanteValorDescripción
CREDITS_GROUP1Lista de los desarrolladores del núcleo
CREDITS_GENERAL2Créditos generales: Diseño del lenguaje y concepto, autores de PHP y módulos SAPI.
CREDITS_SAPI4Lista de los módulos API para PHP y sus autores.
CREDITS_MODULES8Lista de los módulos de extensión para PHP y sus autores.
CREDITS_DOCS16Los créditos del equipo de documentación.
CREDITS_FULLPAGE32Normalmente se utiliza en combiación con otras opciones.Indica que una página HTML independiente debe ser mostrada incluyendo la información indicada por otras opciones.
CREDITS_QA64Los créditos del equipo de testers.
CREDITS_ALL-1Todos los créditos, es equivalente a usar:CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_QA CREDITS_FULLPAGE. Genera una página HTML independiente con las apropiadas etiquetas. Este es el valor por defecto.
Constantes dephpinfo()
ConstanteValorDescripción
INFO_GENERAL1La línea de comandos de configuración,php.iniruta, fecha del build, servidor Web, sistema y demás.
INFO_CREDITS2Créditos de PHP. Ver tambiénphpcredits().
INFO_CONFIGURATION4Valores locales y maestros actuales para directivas PHP. Ver tambiénini_get().
INFO_MODULES8Módulos cargados y sus respectivas opciones.
INFO_ENVIRONMENT16Información de variables de entorno, también está disponible en$_ENV.
INFO_VARIABLES32Muestra todas lasvariables predefinidasdesdeEGPCS(Entorno, GET, POST, Cookie, Server).
INFO_LICENSE64Información de la licencia de PHP. Ver también» FAQ de la licencia.
INFO_ALL-1Muestra todas las directivas que se han indicado hasta ahora. Este es el valor por defecto.
INI constants
ConstanteValorDescripción
INI_USER1Sin uso
INI_PERDIR2Sin uso
INI_SYSTEM4Sin uso
INI_ALL7Sin uso

Constantes de aserción, estos valores se usan para definir opciones de aserción enassert_options().

Constantesassert()
ConstanteOpción INIDescripción
ASSERT_ACTIVEassert.activeHabilita la evaluación deassert().
ASSERT_CALLBACKassert.callbackLlamada de retorno a llamar en caso que falle la aserción.
ASSERT_BAILassert.bailTerminar la ejecucción al finalizar aserciones.
ASSERT_WARNINGassert.warningGenera un warning PHP por cada aserción que falle
ASSERT_QUIET_EVALassert.quiet_evalDesactivaerror_reportingdurante la evaluación de expresiones de aserción.

Las siguientes constantes están disponibles únicamente si se está ejecutando el sistema operativo Windows y muestran información sobre las diferentes versiones. Esto hace posible el detectar determinadas características para poder hacer uso de ellas. Disponibles desde PHP 5.3.0.

Constantes específicas para Windows
ConstanteDescripción
PHP_WINDOWS_VERSION_MAJOREl número mayor de la versión de Windows, que puede tener el valor4(NT4/Me/98/95),5(XP/2003 R2/2003/2000) o6(Vista/2008/7/8/8.1).
PHP_WINDOWS_VERSION_MINOREl número menor de la versión de Windows, que puede tener el valor0(Vista/2008/2000/NT4/95),1(XP),2(2003 R2/2003/XP x64),10(98) o90(ME).
PHP_WINDOWS_VERSION_BUILDEl número del build de Windows (por ejemplo, Windows Vista con SP1 sería el build número 6001)
PHP_WINDOWS_VERSION_PLATFORMLa plataforma en la que PHP se está ejecutando, su valor es2en Windows Vista/XP/2000/NT4, Server 2008/2003 y en Windows ME/98/95 su valor es1.
PHP_WINDOWS_VERSION_SP_MAJOREl número mayor de la versión del service pack instalado, su valor es0si no hay ningún service pack instalado. Por ejemplo, Windows XP con service pack 3 instalado hará que el valor sea3.
PHP_WINDOWS_VERSION_SP_MINOREl número menor de la versión del service pack instalado, su valor es0si no hay ningún service pack instalado.
PHP_WINDOWS_VERSION_SUITEMASKEl suitemask es una máscara de bits que puede indicar si determinadas características de Windows están instaladas, consulte la siguiente tabla para ver los diferentes valores del campo de bits.
PHP_WINDOWS_VERSION_PRODUCTTYPEContiene el valor usado para determinar las constantesPHP_WINDOWS_NT_*. Este valor puede ser una de las constantesPHP_WINDOWS_NT_*que indica el tipo de sistema que se está usando.
PHP_WINDOWS_NT_DOMAIN_CONTROLLEREl controlador de dominio
PHP_WINDOWS_NT_SERVEREl servidor del sistema (ej. Server 2008/2003/2000), observe que si es un controlador de dominio será informado comoPHP_WINDOWS_NT_DOMAIN_CONTROLLER.
PHP_WINDOWS_NT_WORKSTATIONEs una estación de trabajo (pej. Vista/XP/2000/NT4)

Esta tabla muestra una lista de características que pueden ser comprobadas al usar la máscara de bitsPHP_WINDOWS_VERSION_SUITEMASK.

Windows suitemask campos de bits
BitsDescripción
0x00000004Los componentes de Microsoft BackOffice están instalados.
0x00000400Windows Server 2003, Web Edition está instalado.
0x00004000Windows Server 2003, Compute Cluster Edition está instalado.
0x00000080Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition o Windows 2000 Datacenter Server está instalado.
0x00000002Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server, o Windows NT Server 4.0 Enterprise Edition está instalado.
0x00000040Windows XP Embedded está instalado.
0x00000200Windows Vista Home Premium, Windows Vista Home Basic, o Windows XP Home Edition está instalado.
0x00000100Escritorio remoto habilitado, limitado a una sesión interactiva. Este valor está definido a no ser que el sistema se ejecute en modo de servidor de aplicaciones.
0x00000001Microsoft Small Business Server fue instalado en el sistema, pero quizá ha sido actualizado a otra versión de Windows.
0x00000020Microsoft Small Business Server está instalado con la restricción de licencia en vigor.
0x00002000Windows Storage Server 2003 R2 o Windows Storage Server 2003 está instalado.
0x00000010Terminal Services está instalado. Este valor siempre está definido. En caso que lo esté pero0x00000100no, entonces el sistema estará ejecutándose en modo de servidor de aplicaciones.
0x00008000Windows Home Server está instalado.


Funciones de Opciones/Info de PHP


assert_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_optionsEstablecer/obtener valores de las directivas relacionadas con las aserciones

Descripción

assert_options(int$what,mixed$value= ?):mixed

Se utiliza para establecer el valor de las diferentes opciones de la funciónassert()o consultar su valor actual.

Parámetros

what

Assert Options
OpciónConfiguración inicialValor predeterminadoDescripción
ASSERT_ACTIVEassert.active1Activa la funciónassert()
ASSERT_WARNINGassert.warning1Cada vez que una aserción falla se genera una advertencia
ASSERT_BAILassert.bail0Termina la ejecución cuando falla una aserción
ASSERT_QUIET_EVALassert.quiet_eval0Desactiva la directiva error_reporting durante la evaluación de la aserción
ASSERT_CALLBACKassert.callback(null)Función que se encargará de gestionar las aserciones cuando fallen

value

Nuevo valor para la directiva.

Valores devueltos

Devuelve el valor original de cualquiera de las opciones ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deassert_options()

<?php
// Esta es nuestra función manejadora
// de los fallos en un aserción
functionassert_failure()
{
echo
'Assert failed';
}

// Esta es nuestra función de test
functiontest_assert($parameter)
{
assert(is_bool($parameter));
}

// Establecemos nuestras propias opciones para gestionar las aserciones
// Activamos las aserciones
assert_options(ASSERT_ACTIVE,true);
// Si una aserción falla se detiene la ejecución
assert_options(ASSERT_BAIL,true);
// Si una aserción falla NO se genera una advertencia
assert_options(ASSERT_WARNING,false);
// Establecemos la función 'assert_failure' como manejadora (callback) de las aserciones
assert_options(ASSERT_CALLBACK,'assert_failure');

// Creamos una aserción la cual queremos que falle
test_assert(1);

// Este código nunca se ejecuta porque ASSERT_BAIL
// está a TRUE
echo'Never reached';
?>

Ver también

  • assert()



Aserción

(No version information available, might only be in Git)

AserciónVerifica si la aserción esfalse

Descripción

PHP 5 y 7

assert(mixed$assertion,string$description= ?):bool

PHP 7

assert(mixed$assertion,Throwable$exception= ?):bool

La funciónassert()revisará el parámetroassertionproporcionado y tomará la acción apropiada si su resultado esfalse.

Aserciones tradicionales (PHP 5 y 7)

Si el parámetroassertiones proporcionado como un string será evaluado como código PHP por la funciónassert(). Las ventajas de un parámetroassertioncomo string es que son menos sobrecargados cuando la comprobación de la aserción está deshabilitada y los mensajes que contienen la expresiónassertion, la expresión falla. Esto significa que si pasa una condición de tipo boolean comoassertionesta condición no se mostrará como parámetro a la función de aserción la cual tiene que haber definido con la funciónassert_options(), la condición es convertida a un string antes de llamar ese manejador de función, y el tipo booleanfalsees convertido como el string vacío.

Las aserciones deberían ser utilizadas solamente como una característica de depuración. Debería utilizarlas para las revisiones de buen funcionamiento las cuales comprueban las condiciones que siempre deberían sertruey que indican algunos errores de programación o si no, para revisar la presencia de algunas características, como funciones de extensión o ciertos límites del sistema y características.

Las aserciones no deberían utilizarse para operaciones normales en tiempo de ejecución como revisiones de parámetros de entrada. Como regla general su código siempre debería ser capaz de funcionar correctamente aún si la verificación de aserción no está activada.

El comportamiento de la funciónassert()podría ser configurado por la funciónassert_options()o por .ini-settings el cual está descrito en la página del manual de esas funciones.

La funciónassert_options()y/o la directiva de configuraciónASSERT_CALLBACKpermite que una función de llamada de retorno sea establecida para manejar aseciones fallidas.

Las llamadas de retornoassert()son particularmente útiles para construir conjuntos de pruebas automatizadas porque le permiten capturar fácilmente el código pasado a la aserción, junto con la información en donde fue hecha la aserción. Mientras que la información puede ser capturada a través de otros métodos, utilizar asernciones lo hace mucho más rápido y más fácil!

La función de llamada de retorno debería aceptar tres argumentos. El primero contendrá el fichero en que falló la aserción. El segundo contendrá la línea en la que falló la aserción y el tercer argumento contendrá la expresión que falló (si la hubiera — valores literales tales como 1 o "dos" no se pasarán a través de este argumento). Los usuarios de PHP 5.4.8 y versiones posteriores también podrían proveer un cuarto argumento opcional, que contendrá el parámetrodescriptionproporcionado a la funciónassert(), si fue establecido.

Expectativas (solamente PHP 7)

La funciónassert()es una construcción de lenguaje en PHP 7, que permite la definición de expectativas: las aserciones que surten efecto en ambientes de desarrollo y pruebas, pero que se optimizan para que tengan costo cero en la producción.

************* desde aqui *************** Mientras queassert_options()puede ser utilizada para controlar el comportamiento como se describe anteriormente por la compatibilidad con versiones anteriores, el código PHP 7 sólo debería usar las dos directivas nuevas de configuración para controlar el comportamiento deassert()y no llamar aassert_options().

*************** DESDE AQUI **************** PHP 7 configuration directives forassert()
DirectiveDefault valuePossible values
zend.assertions1
  • 1: generate and execute code (development mode)
  • 0: generate code but jump around it at runtime
  • -1: do not generate code (production mode)
assert.exception0
  • 1: throw when the assertion fails, either by throwing the object provided as theexceptionor by throwing a newAssertionErrorobject ifexceptionwasn't provided
  • 0: use or generate aThrowableas described above, but only generate a warning based on that object rather than throwing it (compatible with PHP 5 behaviour)

Parámetros

assertion

The assertion. In PHP 5, this must be either astringto be evaluated or abooleanto be tested. In PHP 7, this may also be any expression that returns a value, which will be executed and the result used to indicate whether the assertion succeeded or failed.

description

An optional description that will be included in the failure message if theassertionfails.

exception

In PHP 7, the second parameter can be aThrowableobject instead of a descriptivestring, in which case this is the object that will be thrown if the assertion fails and theassert.exceptionconfiguration directive is enabled.

Valores devueltos

falseif the assertion is false,trueotherwise.

Historial de cambios

VersiónDescripción
7.0.0assert()is now a language construct and not a function.assertion()can now be an expression. The second parameter is now interpreted either as anexception(if aThrowableobject is given), or as thedescriptionsupported from PHP 5.4.8 onwards.
5.4.8Thedescriptionparameter was added. Thedescriptionis also now provided to a callback function inASSERT_CALLBACKmode as the fourth argument.

Ejemplos

Traditional assertions (PHP 5 and 7)

Ejemplo #1 Handle a failed assertion with a custom handler

<?php
// Active assert and make it quiet
assert_options(ASSERT_ACTIVE,1);
assert_options(ASSERT_WARNING,0);
assert_options(ASSERT_QUIET_EVAL,1);

// Create a handler function
functionmy_assert_handler($file,$line,$code)
{
echo
"<hr>Assertion Failed:
File '
$file'<br />
Line '
$line'<br />
Code '
$code'<br /><hr />";
}

// Set up the callback
assert_options(ASSERT_CALLBACK,'my_assert_handler');

// Make an assertion that should fail
assert('mysql_query("")');
?>

Ejemplo #2 Using a custom handler to print a description

<?php
// Active assert and make it quiet
assert_options(ASSERT_ACTIVE,1);
assert_options(ASSERT_WARNING,0);
assert_options(ASSERT_QUIET_EVAL,1);

// Create a handler function
functionmy_assert_handler($file,$line,$code,$desc=null)
{
echo
"Assertion failed at$file:$line:$code";
if (
$desc) {
echo
":$desc";
}
echo
"\n";
}

// Set up the callback
assert_options(ASSERT_CALLBACK,'my_assert_handler');

// Make an assertion that should fail
assert('2 < 1');
assert('2 < 1','Two is less than one');
?>

El resultado del ejemplo sería:

 Assertion failed at test.php:21: 2 < 1
 Assertion failed at test.php:22: 2 < 1: Two is less than one
 

Expectations (PHP 7 only)

Ejemplo #3 Expectations without a custom exception

<?php
assert
(true==false);
echo
'Hi!';
?>

Withzend.assertionsset to 0, the above example will output:

Hi!

Withzend.assertionsset to 1 andassert.exceptionset to 0, the above example will output:

Warning: assert(): assert(true == false) failed in - on line 2
Hi!

Withzend.assertionsset to 1 andassert.exceptionset to 1, the above example will output:

Fatal error: Uncaught AssertionError: assert(true == false) in -:2
Stack trace:
#0 -(2): assert(false, 'assert(true == ...')
#1 {main}
  thrown in - on line 2

Ejemplo #4 Expectations with a custom exception

<?php
classCustomErrorextendsAssertionError{}

assert(true==false, newCustomError('True is not false!'));
echo
'Hi!';
?>

Withzend.assertionsset to 0, the above example will output:

Hi!

Withzend.assertionsset to 1 andassert.exceptionset to 0, the above example will output:

Warning: assert(): CustomError: True is not false! in -:4
Stack trace:
#0 {main} failed in - on line 4
Hi!

Withzend.assertionsset to 1 andassert.exceptionset to 1, the above example will output:

Fatal error: Uncaught CustomError: True is not false! in -:4
Stack trace:
#0 {main}
  thrown in - on line 4

Ver también

  • assert_options()- Establecer/obtener valores de las directivas relacionadas con las aserciones



cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_titleReturns the current process title

Descripción

cli_get_process_title():?string

Returns the current process title, as set bycli_set_process_title(). Note that this may not exactly match what is shown inpsortop, depending on your operating system.

This function is available only inCLImode.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Return a string with the current process title ornullon error.

Errores/Excepciones

AnE_WARNINGwill be generated if the operating system is unsupported.

Ejemplos

Ejemplo #1cli_get_process_title()example

<?php
echo"Process title: ".cli_get_process_title() ."\n";
?>

Ver también



cli_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_titleSets the process title

Descripción

cli_set_process_title(string$title):bool

Sets the process title visible in tools such astopandps. This function is available only inCLImode.

Parámetros

title

The new title.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

AnE_WARNINGwill be generated if the operating system is unsupported.

Ejemplos

Ejemplo #1cli_set_process_title()example

<?php
$title
="My Amazing PHP Script";
$pid=getmypid();// you can use this to see your process title in ps

if (!cli_set_process_title($title)) {
echo
"Unable to set process title for PID$pid...\n";
exit(
1);
} else {
echo
"The process title '$title' for PID$pidhas been set for your process!\n";
sleep(5);
}
?>

Ver también



dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dlCarga una extensión de PHP durante la ejecución

Descripción

dl(string$library):bool

Carga la extensión PHP dada por el parámetrolibrary.

Utilice la funciónextension_loaded()para comprobar si la extensión ya está cargada o no. Funciona tanto para extensiones ya integradas en PHP o para extensiones que se han cargado dinámicamente (ya sea a través dephp.iniodl()).

Advertencia

Esta función ha sido eliminada de la mayoría de las SAPI en PHP 5.3.0, y de PHP-FPM en PHP 7.0.0.

Parámetros

library

Este parámetro essolamenteel fichero de la extensión a cargar el cual depende del sistema operativo. Por ejemplo, la extensiónsockets(si se compila como librería, no como parte de PHP) Se llamarásockets.soen sistemas Unix mientras que en Windows se llamaráphp_sockets.dll.

El directorio desde donde la extensión será cargada también depende del sistema operativo:

En Windows - a no ser que se defina explicitamente enphp.ini, la extensión será cargada por defecto desdeC:\php4\extensions\(PHP4) oC:\php5\en (PHP 5).

Unix - a no ser que se defina enphp.ini, el directorio de extensiones por defecto depende de

  • Si PHP fué compilado con la opción--enable-debugo no
  • Si PHP fué comiplado con soporte (experimental) ZTS (Zend Thread Safety) o no
  • El módulo interno actualZEND_MODULE_API_NO(Número interno del API Zend, que es básicamente la fecha en que se produjo un cambio de versión, p.ej.20010901)
Teniendo esto en cuenta el directorio por defecto será<install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO, p.ej./usr/local/php/lib/php/extensions/debug-non-zts-20010901o/usr/local/php/lib/php/extensions/no-debug-zts-20010901.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error. Si la funcionalidad de cargar módulos no está disponible o ha sido deshabilitada (ya sea activandoenable_dloff enphp.ini) Se producirá unE_ERRORy se parará la ejecucción de PHP. Sidl()falló porque la librería especificacda no pudo cargarse a demás defalsese producirá un mensajeE_WARNING.

Ejemplos

Ejemplo #1 Ejemplos dedl()

<?php
// En este ejemplo se carga una extensión u otra dependiendo del sistema operativo
if (!extension_loaded('sqlite')) {
if (
strtoupper(substr(PHP_OS,0,3)) ==='WIN') {
dl('php_sqlite.dll');
} else {
dl('sqlite.so');
}
}

// O si la constante PHP_SHLIB_SUFFIX está disponible desde PHP 4.3.0
if (!extension_loaded('sqlite')) {
$prefix= (PHP_SHLIB_SUFFIX==='dll') ?'php_':'';
dl($prefix.'sqlite.'.PHP_SHLIB_SUFFIX);
}
?>

Historial de cambios

VersiónDescripción
7.0.0dl()está deshabilitado en PHP-FPM.
5.3.9dl()está deshabilitado en PHP-FPM, aunque se desaconseja.
5.3.0dl()está desactivado en algunos módulos SAPI por problemas de estabilidad. Los únicos modulos SAPI que permitendl()son: CLI, CGI and Embed. En su lugar usar las directivasDirectivas de carga de extensiones

Notas

Nota:

dl()nose soporta cuando PHP es compilado con soporte ZTS. Use en su lugarDirectivas de carga de extensionesinstead.

Nota:

dl()es sensible a mayúsculas en sistemas Unix.

Ver también



extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loadedEncontrar si una extensión está cargada

Descripción

extension_loaded(string$name):bool

Encuentra si la extensión está cargada.

Parámetros

name

El nombre de la extensión. Este parámetro considera el uso de mayúsculas/minúsculas.

Es posible ver los nombres de varias extensiones usandophpinfo(), o si usted usa la versiónCGIoCLIde PHP, puede usar la bandera-mpara listar todas las extensiones disponibles:

$ php -m
[PHP Modules]
xml
tokenizer
standard
sockets
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

Valores devueltos

Devuelvetruesi la extensión identificada pornombreestá cargada,falsede lo contrario.

Ejemplos

Ejemplo #1 Ejemplo deextension_loaded()

<?php
if (!extension_loaded('gd')) {
if (!
dl('gd.so')) {
exit;
}
}
?>

Ver también

  • get_loaded_extensions()- Devuelve un array con los nombres de todos los módulos compilados y cargados
  • get_extension_funcs()- Devuelve una matriz con los nombres de funciones de un módulo
  • phpinfo()- Muestra información sobre la configuración de PHP
  • dl()- Carga una extensión de PHP durante la ejecución
  • function_exists()- Devuelve true si la función dada ha sido definida



gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cyclesFuerza la recolección de los ciclos de basura existentes

Descripción

gc_collect_cycles():int

Recogida de las fuerzas de los ciclos de basura existentes.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el número de ciclos de recogida.



gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disableDesactiva el recolector de referencia circular

Descripción

gc_disable():void

Desactiva el recolector de referencia circular.zend.enable_gca0.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.



gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enableActiva el colector de referencia circular

Descripción

gc_enable():void

Activa el colector de referencia circular, estableciendozend.enable_gca1.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.

Ver también



gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabledDevuelve el estado del colector de referencia circular

Descripción

gc_enabled():bool

Devuelve el estado del colector de referencia circular.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetruesi el recolector de basura está activado,falseen caso contrario.

Ejemplos

Ejemplo #1 Ejemplo degc_enabled()

<?php
if(gc_enabled())gc_collect_cycles();
?>



gc_mem_caches

(PHP 7, PHP 8)

gc_mem_cachesReclaims memory used by the Zend Engine memory manager

Descripción

gc_mem_caches():int

Reclaims memory used by the Zend Engine memory manager.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returns the number of bytes freed.

Ver también



gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_statusGets information about the garbage collector

Descripción

gc_status():array

Gets information about the current state of the garbage collector.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returns an associative array with the following elements:

  • "runs"
  • "collected"
  • "threshold"
  • "roots"

Ejemplos

Ejemplo #1gc_status()Usage

<?php

// create object tree that needs gc collection
$a= newstdClass();
$a->b= [];
for (
$i=0;$i<100000;$i++) {
$b= newstdClass();
$b->a=$a;
$a->b[] =$b;
}
unset(
$a);
unset(
$b);
gc_collect_cycles();

var_dump(gc_status());

El resultado del ejemplo sería algo similar a:

array(4) {
  ["runs"]=>
  int(5)
  ["collected"]=>
  int(100002)
  ["threshold"]=>
  int(50001)
  ["roots"]=>
  int(0)
}

Ver también



get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_varObtiene el valor de una opción de configuración de PHP

Descripción

get_cfg_var(string$option):mixed

Obtiene el valor de una opción de configuración de PHP.

Esta función no retornará información de configuración establecida cuando PHP fue compilado, o lee un fichero de configuración de Apache.

Para comprobar si el sistema está usando unfichero de configuración, intente recuperar el valor de la opción de configuración cfg_file_path. Si está disponible, un fichero de configuración está siendo utilizado.

Parámetros

option

El nombre de la opción de configuración.

Valores devueltos

Devuelve el valor actual de la variable de configuración de PHP especificada poroption, ofalsesi se produce un error.

Historial de cambios

VersiónDescripción
5.3.0get_cfg_var()se fijó para ser capaz de retornar un "array" con las opciones ini.

Ver también

  • ini_get()- Devuelve el valor de una directiva de configuración
  • ini_get_all()- Obtiene todas las opciones de configuración



get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_userObtiene el nombre del propietario del script PHP actual

Descripción

get_current_user():string

Devuelve el nombre del propietario del script PHP actual.

Valores devueltos

Devuelve el nombre de usuario como un string.

Ejemplos

Ejemplo #1get_current_user()ejemplo

<?php
echo'Propietario script actual: '.get_current_user();
?>

El resultado del ejemplo sería algo similar a:

Propietario script actual: SYSTEM

Ver también



get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constantsDevuelve un array asociativo con los nombres de todas las constantes y sus valores

Descripción

get_defined_constants(bool$categorize=false):array

Devuelve los nombres y valores de todas las constantes definidas actualmente. Esto incluye las creadas por las extensiones, así como las creadas con la funcióndefine().

Parámetros

categorize

Provoca que la función retorne un array multi-dimensional con categorias en las claves de la primera dimensión y constantes y sus valores en la segunda dimensión.

<?php
define
("MI_CONSTANTE",1);
print_r(get_defined_constants(true));
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [Core] => Array
        (
            [E_ERROR] => 1
            [E_WARNING] => 2
            [E_PARSE] => 4
            [E_NOTICE] => 8
            [E_CORE_ERROR] => 16
            [E_CORE_WARNING] => 32
            [E_COMPILE_ERROR] => 64
            [E_COMPILE_WARNING] => 128
            [E_USER_ERROR] => 256
            [E_USER_WARNING] => 512
            [E_USER_NOTICE] => 1024
            [E_ALL] => 2047
            [TRUE] => 1
        )

    [pcre] => Array
        (
            [PREG_PATTERN_ORDER] => 1
            [PREG_SET_ORDER] => 2
            [PREG_OFFSET_CAPTURE] => 256
            [PREG_SPLIT_NO_EMPTY] => 1
            [PREG_SPLIT_DELIM_CAPTURE] => 2
            [PREG_SPLIT_OFFSET_CAPTURE] => 4
            [PREG_GREP_INVERT] => 1
        )

    [user] => Array
        (
            [MI_CONSTANTE] => 1
        )

)

Valores devueltos

Devuelve un array de arrays nombre_constante => valor_constante, opcionalmente agrupados por nombre de extensión registrando la constante.

Historial de cambios

VersiónDescripción
5.3.1Sólo para Windows: las constantes fundamentales se clasifican enCore, previamentemhash.
5.3.0Constantes fundamentales se clasifican enCore, antesinternal. En Windows, las constantes fundamentales se clasifican enmhash.
5.2.11El parámetrocategorizeahora funciona correctamente. Anteriormente, el parámetrocategorizeera interpretado como!is_null($categorize), por lo que cualquier valor distinto denullfuerza a las constantes a ser clasificadas.

Ejemplos

Ejemplo #1 Ejemplo deget_defined_constants()

<?php
print_r
(get_defined_constants());
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [E_ERROR] => 1
    [E_WARNING] => 2
    [E_PARSE] => 4
    [E_NOTICE] => 8
    [E_CORE_ERROR] => 16
    [E_CORE_WARNING] => 32
    [E_COMPILE_ERROR] => 64
    [E_COMPILE_WARNING] => 128
    [E_USER_ERROR] => 256
    [E_USER_WARNING] => 512
    [E_USER_NOTICE] => 1024
    [E_ALL] => 2047
    [TRUE] => 1
)

Ver también



get_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcsDevuelve una matriz con los nombres de funciones de un módulo

Descripción

get_extension_funcs(string$module_name):array

Esta función devuelve los nombres de todas las funciones definidas en el módulo indicado pornombre_modulo.

Parámetros

module_name

El nombre del módulo.

Nota:

Este parámetro debe estar enminúsculas.

Valores devueltos

Devuelve una matriz con todas las funciones, ofalsesinombre_modulono es una extensión válida.

Ejemplos

Ejemplo #1 Imprime las funciones XML

<?php
print_r
(get_extension_funcs("xml"));
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [0] => xml_parser_create
    [1] => xml_parser_create_ns
    [2] => xml_set_object
    [3] => xml_set_element_handler
    [4] => xml_set_character_data_handler
    [5] => xml_set_processing_instruction_handler
    [6] => xml_set_default_handler
    [7] => xml_set_unparsed_entity_decl_handler
    [8] => xml_set_notation_decl_handler
    [9] => xml_set_external_entity_ref_handler
    [10] => xml_set_start_namespace_decl_handler
    [11] => xml_set_end_namespace_decl_handler
    [12] => xml_parse
    [13] => xml_parse_into_struct
    [14] => xml_get_error_code
    [15] => xml_error_string
    [16] => xml_get_current_line_number
    [17] => xml_get_current_column_number
    [18] => xml_get_current_byte_index
    [19] => xml_parser_free
    [20] => xml_parser_set_option
    [21] => xml_parser_get_option
    [22] => utf8_encode
    [23] => utf8_decode
)

Ver también



get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_pathObtiene la opción de configuración include_path actual

Descripción

get_include_path():string

Obtiene el valor actual de la opción de configuracióninclude_path.

Valores devueltos

Devuelve la ruta, como una cadena.

Ejemplos

Ejemplo #1 Ejemplo deget_include_path()

<?php
echoget_include_path();

// O utilizando ini_get()
echoini_get('include_path');
?>

Ver también



get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_filesDevuelve un array con los nombres de los archivos incluidos o requeridos

Descripción

get_included_files():array

Obtiene los nombres de todos los archivos que han sido incluidos usandoinclude,include_once,requireorequire_once.

Valores devueltos

Devuelve un array con los nombres de los archivos.

El script llamado originalmente es considerado un "archivo incluido", así que será listado junto con los archivos referenciados por la familia de funcionesinclude.

Los archivos que son incluidos o requeridos múltiples veces solo aparecen una vez en el array devuelto.

Ejemplos

Ejemplo #1 Ejemplo deget_included_files()

<?php
// Este archivo es abc.php

include'test1.php';
include_once
'test2.php';
require
'test3.php';
require_once
'test4.php';

$archivos_incluidos=get_included_files();

foreach (
$archivos_incluidosas$nombre_archivo) {
echo
"$nombre_archivo\n";
}

?>

El resultado del ejemplo sería:

/path/to/abc.php
/path/to/test1.php
/path/to/test2.php
/path/to/test3.php
/path/to/test4.php

Ver también



get_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensionsDevuelve un array con los nombres de todos los módulos compilados y cargados

Descripción

get_loaded_extensions(bool$zend_extensions= false):array

Esta función devuelve los nombres de todos los módulos compilados y cargados en el intérprete de PHP.

Parámetros

zend_extensions

Sólo retorna extensiones Zend, si no, las extensiones regulares, como mysqli. El valor predeterminado esfalse(retorna extensiones regulares).

Valores devueltos

Devuelve un array indexado de todos los nombres de los módulos.

Historial de cambios

VersiónDescripción
5.2.4Fue añadido el parámetro opcionalzend_extensions

Ejemplos

Ejemplo #1get_loaded_extensions()

<?php
print_r
(get_loaded_extensions());
?>

El resultado del ejemplo sería algo similar a:

Array
(
   [0] => xml
   [1] => wddx
   [2] => standard
   [3] => session
   [4] => posix
   [5] => pgsql
   [6] => pcre
   [7] => gd
   [8] => ftp
   [9] => db
   [10] => calendar
   [11] => bcmath
)

Ver también

  • get_extension_funcs()- Devuelve una matriz con los nombres de funciones de un módulo
  • extension_loaded()- Encontrar si una extensión está cargada
  • dl()- Carga una extensión de PHP durante la ejecución
  • phpinfo()- Muestra información sobre la configuración de PHP



get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpcObtiene el valor actual de configuración de magic_quotes_gpc

Advertencia

Esta función ha sido declaradaOBSOLETAa partir de PHP 7.4.0, y esELIMINADAdesde PHP 8.0.0. Su uso está totalmente desaconsejado.

Descripción

get_magic_quotes_gpc():bool

Siempre retornafalse.

Valores devueltos

Siempre retornafalse.

Historial de cambios

VersiónDescripción
7.4.0Esta función ha quedado en desuso.

Ver también



get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtimeObtiene el valor de configuración activo actual de magic_quotes_runtime

Advertencia

Esta función ha sido declaradaOBSOLETAa partir de PHP 7.4.0. Su uso está totalmente desaconsejado

Descripción

get_magic_quotes_runtime():bool

Devuelve el valor de configuración activo actual demagic_quotes_runtime.

Valores devueltos

Devuelve 0 si magic_quotes_runtime está off, 1 en caso contrario. O siempre devuelvefalsea partir de PHP 5.4.0.

Historial de cambios

VersiónDescripción
7.4.0Esta función es obsoleta.
5.4.0Siempre devuelvefalsedebido a que la característica de comillas mágicas ha sido eliminada de PHP.

Ejemplos

Ejemplo #1get_magic_quotes_runtime()ejemplo

<?php
// Comprueba si magic_quotes_runtime está activado
if(get_magic_quotes_runtime())
{
// Desactivar
set_magic_quotes_runtime(false);
}
?>

Ver también

  • get_magic_quotes_gpc()- Obtiene el valor actual de configuración de magic_quotes_gpc
  • set_magic_quotes_runtime()



get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_filesAlias deget_included_files()

Descripción

Esta función es un alias de:get_included_files().



get_resources

(PHP 7, PHP 8)

get_resourcesReturns active resources

Descripción

get_resources(?string$type=null):array

Returns an array of all currently activeresources, optionally filtered by resource type.

Nota:This function is meant for debugging and testing purposes. It is not supposed to be used in production environments, especially not to access or even manipulate resources which are normally not accessible (e.g. the underlying stream resource ofSplFileObjectinstances).

Parámetros

type

If defined, this will causeget_resources()to only return resources of the given type.A list of resource types is available.

If thestringUnknownis provided as the type, then only resources that are of an unknown type will be returned.

If omitted, all resources will be returned.

Valores devueltos

Returns anarrayof currently active resources, indexed by resource number.

Historial de cambios

VersiónDescripción
8.0.0typeis nullable now.

Ejemplos

Ejemplo #1 Unfilteredget_resources()

<?php
$fp
=tmpfile();
var_dump(get_resources());
?>

El resultado del ejemplo sería algo similar a:

array(1) {
  [1]=>
  resource(1) of type (stream)
}

Ejemplo #2 Filteredget_resources()

<?php
$fp
=tmpfile();
var_dump(get_resources('stream'));
var_dump(get_resources('curl'));
?>

El resultado del ejemplo sería algo similar a:

array(1) {
  [1]=>
  resource(1) of type (stream)
}
array(0) {
}

Ver también



getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenvObtiene el valor de una variable de entorno

Descripción

getenv(string$varname):string

Obtiene el valor de una variable de entorno.

Se puede ver una lista de todas las variables de entorno usandophpinfo(). Muchas de estas variables están listadas bajo la especificación» RFC 3875, específicamente la sección 4.1, "Request Meta-Variables".

Parámetros

varname

El nombre de variable.

Valores devueltos

Devuelve el valor de la variable de entornovarname, ofalsesi la variable entornovarnameno existe.

Ejemplos

Ejemplo #1 Ejemplo degetenv()

<?php
// Ejemplo de uso de getenv()
$ip=getenv('REMOTE_ADDR');

// O simplemente use una Superglobal ($_SERVER o $_ENV)
$ip=$_SERVER['REMOTE_ADDR'];
?>

Ver también



getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmodObtiene la hora de la última modificación de la página

Descripción

getlastmod():int

Obtiene la hora de la última modificación del script principal de la ejecución.

Si está interesado en obtener la hora de la última modificación de un archivo diferente, considere el uso defilemtime().

Valores devueltos

Devuelve la hora de la última modificación de la página actual. El valor devuelto es una marca de tiempo Unix, apropiada para ser pasada adate(). Devuelvefalseen caso de fallo.

Ejemplos

Ejemplo #1 Ejemplo degetlastmod()

<?php
// imprime p.ej. 'Ultima modificación: March 04 1998 20:43:59.'
echo"Ultima modificación: ".date("F d Y H:i:s.",getlastmod());
?>

Ver también



getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygidObtener el GID del dueño del script PHP

Descripción

getmygid():int

Obtiene el ID de grupo del script actual.

Valores devueltos

Devuelve el ID de grupo del script actual, ofalseen caso de error.

Ver también



getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinodeObtiene el inode del script actual

Descripción

getmyinode():int

Obtiene el inode del script actual.

Valores devueltos

Devuelve el inodo del script actual como un entero, ofalseen caso de error.

Ver también



getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypidObtiene el ID del proceso PHP

Descripción

getmypid():int

Obtiene el ID del proceso PHP actual.

Valores devueltos

Devuelve el ID del proceso PHP actual, ofalsesi ocurre un error.

Notas

Advertencia

Los IDs de proceso no son únicos, por lo tanto son una fuente débil de entropía. Es recomendable no depender en ids de proceso en contextos sujetos a consideraciones de seguridad.

Ver también



getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuidObtiene el UID del dueño del script PHP

Descripción

getmyuid():int

Obtiene el ID de usuario para el script actual.

Valores devueltos

Devuelve el ID de usuario del script actual, ofalseen caso de error.

Ver también



getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getoptObtiene las opciones de la lista de argumentos de la línea de comandos

Descripción

getopt(string$options,array$longopts= ?):array

Analiza las opciones pasadas al script.

Parámetros

options
Cada carácter de esta cadena de texto se usará como un carácter de opción y se comparará con aquellas opciones pasadas al script que comiencen con un guión simple (-).Por ejemplo, el string de opciones"x"reconocerá la opción-x.Sólo se permiten a-z, A-Z y 0-9.
longopts
Matriz de opciones. Cada elemento de este array se usará como texto de opciones y se compararán con aquellas opciones pasadas al script que comiencen con dos guiones (--).Por ejemplo, longopts tuviera un elemento con"opt", reconocería la opción--opt.

El parámetrooptionspuede contener los siguientes elementos:

  • Caracteres individuales (no acepta valores)
  • Caracteres seguidos por dos puntos (el parámetro exige un valor)
  • Caracteres seguidos dos veces por dos puntos (valor opcional)
Los valores de opción serán el primer argumento tras el string. Si se requiere un valor, no importa si este tiene espacios en blanco delante o no. Véase la nota.

Nota:Los valores opcionales no aceptan un" "(espacio) como separador.

Nota:

El formato deoptionsy delongoptses casi igual. La única diferencia es quelongoptscontiene un array de opciones (donde cada elemento es la opción) mientras queoptionscontiene un string (donde cada carácter es la opción).

Valores devueltos

Esta función devolverá un array de parejas opciones / argumentos, ofalseen caso de error.

Nota:

El análisis de opciones finalizará cuando se encuentre alguna no-opción. Todo lo que haya a continuación será descartado.

Historial de cambios

VersiónDescripción
5.3.0Añadido soporte para usar "=" como separador de argumento/valor.
5.3.0Añadido soporte para valores opcionales (especificado mediante "::").
5.3.0El parámetrolongoptsestá disponible en todos los sistemas.
5.3.0Esta función ya no depende del sistema y funciona también en Windows.

Ejemplos

Ejemplo #1 Ejemplo degetopt(): Lo básico

<?php
// Script example.php
$options=getopt("f:hp:");
var_dump($options);
?>
shell> php example.php -fvalue -h

El resultado del ejemplo sería:

array(2) {
  ["f"]=>
  string(5) "value"
  ["h"]=>
  bool(false)
}

Ejemplo #2 Ejemplo degetopt(): Introducir opciones long

<?php
// Script example.php
$shortopts="";
$shortopts.="f:";// Valor obligatorio
$shortopts.="v::";// Valor opcional
$shortopts.="abc";// Estas opciones no aceptan valores

$longopts= array(
"required:",// Valor obligatorio
"optional::",// Valor opcional
"option",// Sin valores
"opt",// Sin valores
);
$options=getopt($shortopts,$longopts);
var_dump($options);
?>
shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option

El resultado del ejemplo sería:

array(6) {
  ["f"]=>
  string(11) "value for f"
  ["v"]=>
  bool(false)
  ["a"]=>
  bool(false)
  ["required"]=>
  string(5) "value"
  ["optional"]=>
  string(14) "optional value"
  ["option"]=>
  bool(false)
}

Ejemplo #3 Ejemplo degetopt(): Pasar varias opciones como una

<?php
// Script example.php
$options=getopt("abc");
var_dump($options);
?>
shell> php example.php -aaac

El resultado del ejemplo sería:

array(2) {
  ["a"]=>
  array(3) {
    [0]=>
    bool(false)
    [1]=>
    bool(false)
    [2]=>
    bool(false)
  }
  ["c"]=>
  bool(false)
}

Ver también



getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusageObtiene el uso de los recursos actuales

Descripción

getrusage(int$who= 0):array

Esta es una interfaz degetrusage(2). Obtiene datos devueltos de la llamada al sistema.

Parámetros

who

Si el parámetrowhoes 1, getrusage será llamado conRUSAGE_CHILDREN.

Valores devueltos

Devuelve un array asociativo que contiene los datos devueltos por la llamada al sistema. Todas las entradas son accesibles mediante el uso de sus nombres de campo documentado.

Ejemplos

Ejemplo #1getrusage()ejemplo

<?php
$dat
=getrusage();
echo
$dat["ru_oublock"];// número de operaciones de salida en bloque
echo$dat["ru_inblock"];// número de operaciones de entrada de bloques
echo$dat["ru_msgsnd"];// número de mensajes de IPC enviados
echo$dat["ru_msgrcv"];// número de mensajes de IPC recibidos
echo$dat["ru_maxrss"];// tamaño máximo de los conjuntos de residentes
echo$dat["ru_ixrss"];// tamaño de memoria integral compartida
echo$dat["ru_idrss"];// tamaño integral de los datos no compartidos
echo$dat["ru_minflt"];// número de reivindicaciones de página (fallos suaves de página)
echo$dat["ru_majflt"];// número de fallos de página (fallos duros de página)
echo$dat["ru_nsignals"];// número de señales recibidas
echo$dat["ru_nvcsw"];// número de cambios de contexto voluntarios
echo$dat["ru_nivcsw"];// número de cambios de contexto involuntarios
echo$dat["ru_nswap"];// número de intercambios
echo$dat["ru_utime.tv_usec"];// tiempo de usuario utilizado (microsegundos)
echo$dat["ru_utime.tv_sec"];// tiempo de usuario utilizado (segundos)
echo$dat["ru_stime.tv_usec"];// tiempo del sistema utilizado (microsegundos)
?>

Historial de cambios

VersiónDescripción
7.0.0Esta función ahora está soportada en Windows

Notas

Nota:

En Windows,getrusage()solamente devolverá los siguientes miembros:

  • "ru_stime.tv_sec"
  • "ru_stime.tv_usec"
  • "ru_utime.tv_sec"
  • "ru_utime.tv_usec"
  • "ru_majflt"(solo siwhoesRUSAGE_SELF)
  • "ru_maxrss"(solo siwhoesRUSAGE_SELF)

Si agetrusage()se le llama conwhoestablecido a1(RUSAGE_CHILDREN), se recopilan los usos de recursos para los hilos (lo que significa que la función es llamada internamente conRUSAGE_THREAD).

Nota:

En BeOS 2000, solamente se devuelven los siguientes miembros:

  • "ru_stime.tv_sec"
  • "ru_stime.tv_usec"
  • "ru_utime.tv_sec"
  • "ru_utime.tv_usec"

Ver también

  • Página principal de sistema sobregetrusage(2)



ini_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alterAlias deini_set()

Descripción

Esta función es un alias de:ini_set().



ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_allObtiene todas las opciones de configuración

Descripción

ini_get_all(string$extension= ?,bool$details= true):array

Devuelve todas las opciones de configuración registradas.

Parámetros

extension

Un nombre de extensión opcional. Si se establece, la función de retornará únicamente opciones específicas para esa extensión.

details

Recupera los detalles de configuración o sólo el valor actual de cada configuración. Por omisión estrue(recuperar detalles).

Valores devueltos

Devuelve un array asociativo con el nombre de la directiva como la clave del array.

Cuando el parámetrodetailsestrue(por omisión) el array contendráglobal_value(establecido enphp.ini),local_value(tal vez establecido conini_set()o.htaccess), yaccess(el nivel de acceso).

Cuando el parámetrodetailsesfalseel valor será el valor actual de la opción.

Vea lasección del manualpara obtener información sobre lo que significan los niveles de acceso.

Nota:

Es posible que una directiva tenga múltiples niveles de acceso, por lo que elaccessmuestra los valores de máscara de bits adecuado.

Notas

Nota:

ini_get_all()ignora las opciones ini de "array" como pdo.dsn.*.

Historial de cambios

VersiónDescripción
5.3.0Se añadiódetails.

Ejemplos

Ejemplo #1ini_get_all()ejemplos

<?php
print_r
(ini_get_all("pcre"));
print_r(ini_get_all());
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [pcre.backtrack_limit] => Array
        (
            [global_value] => 100000
            [local_value] => 100000
            [access] => 7
        )

    [pcre.recursion_limit] => Array
        (
            [global_value] => 100000
            [local_value] => 100000
            [access] => 7
        )

)
Array
(
    [allow_call_time_pass_reference] => Array
        (
            [global_value] => 0
            [local_value] => 0
            [access] => 6
        )

    [allow_url_fopen] => Array
        (
            [global_value] => 1
            [local_value] => 1
            [access] => 4
        )

    ...

)

Ejemplo #2 Disablingdetails

<?php
print_r
(ini_get_all("pcre",false));// Se añadió en PHP 5.3.0
print_r(ini_get_all(null,false));// Se añadió en PHP 5.3.0
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [pcre.backtrack_limit] => 100000
    [pcre.recursion_limit] => 100000
)
Array
(
    [allow_call_time_pass_reference] => 0
    [allow_url_fopen] => 1
    ...
)

Ver también



ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_getDevuelve el valor de una directiva de configuración

Descripción

ini_get(string$varname):string

En caso de éxito devuelve el valor de una directiva de configuración.

Parámetros

varname

Nombre de la directiva de configuración.

Valores devueltos

Devuelve el valor de la opción de configuración como cadena en caso de éxito, o una cadena vacía para valoresnull. Devuelvefalsesi la opción de configuración no existe.

Ejemplos

Ejemplo #1 Unos cuantos ejemplos de la funciónini_get()

<?php
/*
Dentro del php.ini tenemos las siguientes directivas junto con sus valores iniciales:

display_errors = On
register_globals = Off
post_max_size = 8M
*/

echo'display_errors = '.ini_get('display_errors') ."\n";
echo
'register_globals = '.ini_get('register_globals') ."\n";
echo
'post_max_size = '.ini_get('post_max_size') ."\n";
echo
'post_max_size+1 = '. (ini_get('post_max_size')+1) ."\n";
echo
'post_max_size in bytes = '.return_bytes(ini_get('post_max_size'));

function
return_bytes($val) {
$val=trim($val);
$last=strtolower($val[strlen($val)-1]);
switch(
$last) {
// El modificador 'G' está disponble desde PHP 5.1.0
case'g':
$val*=1024;
case
'm':
$val*=1024;
case
'k':
$val*=1024;
}

return
$val;
}

?>

El resultado del ejemplo sería algo similar a:


display_errors = 1
register_globals = 0
post_max_size = 8M
post_max_size+1 = 9
post_max_size in bytes = 8388608

Notas

Nota:Cuando se consultan valores booleanos

El valor booleanooffserá devuelto como una cadena vacía o "0", mientras que el valor booleanoonserá devuelto será devuelto como "1". Esta función también puede devolver valores iniciales como cadenas.

Nota:Cuando se consultan valores de tamaños de memoria

Muchos valores iniciales de tamaños de memoria, tales comoupload_max_filesize, están almacenados en el ficherophp.inien notación abreviada.ini_get()devolverá la cadena exacta almacenada en el ficherophp.iniyNOsu valor de tipointegerequivalente. Utilizar estos valores en funciones aritméticas puede provocar resultados inesperados. El ejemplo anterior muestra una manera de convertir la notación abreviada a bytes, muy similar a cómo lo hace el código fuente de PHP.

Nota:

ini_get()no puede leer las opciones ini "array" como pdo.dsn.*, devolviendofalseen este caso.

Historial de cambios

VersiónDescripción
5.3.0Anteriormente, se devolvía un string si la opción de configuración no existía. Ahora en su lugar se devuelvefalse.

Ver también

  • get_cfg_var()- Obtiene el valor de una opción de configuración de PHP
  • ini_get_all()- Obtiene todas las opciones de configuración
  • ini_restore()- Restablece el valor de una opción de configuración
  • ini_set()- Establece el valor de una directiva de configuración



ini_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantityGet interpreted size from ini shorthand syntax

Descripción

ini_parse_quantity(string$shorthand):int

Returns the interpreted size in bytes on success from anini shorthand.

Parámetros

shorthand

Ini shorthand to parse, must be a number followed by an optional multiplier. The following multipliers are supported:k/K(1024),m/M(1048576),g/G(1073741824). The number can be a decimal, hex (prefixed with0xor0X), octal (prefixed with0o,0Oor0) or binary (prefixed with0bor0B)

Valores devueltos

Returns the interpreted size in bytes as anint.

Errores/Excepciones

If the value cannot be parsed, or an invalid multiplier is used, anE_WARNINGis raised.

Ejemplos

Ejemplo #1 A fewini_parse_quantity()examples

<?php

var_dump
(ini_parse_quantity('1024'));
var_dump(ini_parse_quantity('1024M'));
var_dump(ini_parse_quantity('512K'));
var_dump(ini_parse_quantity('0xFFk'));
var_dump(ini_parse_quantity('0b1010k'));
var_dump(ini_parse_quantity('0o1024'));
var_dump(ini_parse_quantity('01024'));
var_dump(ini_parse_quantity('Foobar'));
var_dump(ini_parse_quantity('10F'));

?>

El resultado del ejemplo sería algo similar a:


int(1024)
int(1073741824)
int(524288)
int(261120)
int(10240)
int(532)
int(532)

Warning: Invalid quantity "Foobar": no valid leading digits, interpreting as "0" for backwards compatibility
int(0)

Warning: Invalid quantity "10F": unknown multiplier "F", interpreting as "10" for backwards compatibility
int(10)

Ver también

  • ini_get()- Devuelve el valor de una directiva de configuración


ini_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restoreRestablece el valor de una opción de configuración

Descripción

ini_restore(string$varname):void

Restaura una opción de configuración dado su valor original.

Parámetros

varname

El nombre de la opción de configuración.

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1ini_restore()ejemplo

<?php
$setting
='y2k_compliance';

echo
'Valor actual \''.$setting.'\': '.ini_get($setting),PHP_EOL;

ini_set($setting,ini_get($setting) ?0:1);
echo
'Nuevo valor \''.$setting.'\': '.ini_get($setting),PHP_EOL;

ini_restore($setting);
echo
'Valor original \''.$setting.'\': '.ini_get($setting),PHP_EOL;
?>

El resultado del ejemplo sería:

Valor actual 'y2k_compliance': 1
Nuevo valor 'y2k_compliance': 0
Valor original 'y2k_compliance': 1

Ver también

  • ini_get()- Devuelve el valor de una directiva de configuración
  • ini_get_all()- Obtiene todas las opciones de configuración
  • ini_set()- Establece el valor de una directiva de configuración



ini_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_setEstablece el valor de una directiva de configuración

Descripción

ini_set(string$varname,string$newvalue):string

Establece el valor de la directiva de configuración dada. La opción de configuración mantendrá este nuevo valor durante la ejecución del script, y se restaurará cuando acabe el mismo.

Parámetros

varname

No todas las directivas pueden ser modificadas conini_set(). Hay una lista con todas las directivas disponibles en elapéndice.

newvalue

El nuevo valor para la opción.

Valores devueltos

Devuelve el valor anterior en caso de éxito,falseen caso de error.

Ejemplos

Ejemplo #1 Establece una opción ini

<?php
echoini_get('display_errors');

if (!
ini_get('display_errors')) {
ini_set('display_errors','1');
}

echo
ini_get('display_errors');
?>

Ver también



memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usageDevuelve el máximo de memoria asignada por PHP

Descripción

memory_get_peak_usage(bool$real_usage=false):int

Devuelve el máximo de memoria, en bytes, que se ha asignado a su script PHP.

Parámetros

real_usage

Si se deja entruepuede obtener el tamaño real de memoria asignada por el sistema. Si no se establece o esfalse, la memoria utilizada poremalloc()es reportada.

Valores devueltos

Devuelve el máximo de memoria en bytes.

Historial de cambios

VersiónDescripción
5.2.1Compilar con--enable-memory-limitya no es necesario para que esta función exista.
5.2.0Se añadereal_usage.

Ver también



memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usageDevuelve la cantidad de memoria asignada a PHP

Descripción

memory_get_usage(bool$real_usage=false):int

Devuelve la cantidad de memoria, en bytes, que actualmente se asigna a su script PHP.

Parámetros

real_usage

Establecer esto atruepara obtener el tamaño real de memoria asignada por el sistema. Incluyendo las páginas no usadas. Si no se establece o esfalsesolo se informa de la memoria utilizada.

Nota:

PHP no rastrea la memoria que no es asignada poremalloc()

Valores devueltos

Devuelve la cantidad de memoria en bytes.

Historial de cambios

VersiónDescripción
5.2.1Compilar con--enable-memory-limitya no es necesario para que exista esta función.
5.2.0Se añadióreal_usage.

Ejemplos

Ejemplo #1 Amemory_get_usage()ejemplo

<?php
// Este es sólo un ejemplo, los siguientes números
// serán diferentes dependiendo de su sistema

echomemory_get_usage() ."\n";// 36640

$a=str_repeat("Hello",4242);

echo
memory_get_usage() ."\n";// 57960

unset($a);

echo
memory_get_usage() ."\n";// 36744

?>

Ver también



memory_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usageReset the peak memory usage

Descripción

memory_reset_peak_usage():void

Resets the peak memory usage returned by thememory_get_peak_usage()function.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1memory_reset_peak_usage()example

<?php

var_dump
(memory_get_peak_usage());

$a=str_repeat("Hello",424242);
var_dump(memory_get_peak_usage());

unset(
$a);
memory_reset_peak_usage();

$a=str_repeat("Hello",2424);
var_dump(memory_get_peak_usage());

?>

El resultado del ejemplo sería algo similar a:

int(422440)
int(2508672)
int(399208)

Ver también



php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_fileRecupera la ruta de acceso al archivo php.ini cargado

Descripción

php_ini_loaded_file():string

Comprueba si un archivophp.inise ha cargado, y recupera su ruta de acceso.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

La ruta dephp.inicargado, ofalsesi uno no se ha cargado.

Ejemplos

Ejemplo #1php_ini_loaded_file()ejemplo

<?php
$inipath
=php_ini_loaded_file();

if (
$inipath) {
echo
'archivo php.ini cargado: '.$inipath;
} else {
echo
'ningún archivo php.ini ha sido cargado';
}
?>

El resultado del ejemplo sería algo similar a:

Loaded php.ini: /usr/local/php/php.ini

Ver también



php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_filesDevuelve una lista de ficheros .ini procesados del directorio adicional ini

Descripción

php_ini_scanned_files():string

php_ini_scanned_files()devuelve una lista separada por comas de los ficheros de configuración procesados porphp.ini. Los directorios buscados se establecen por una opción de tiempo de compilación y, opcionalmente, por una variable de entorno en tiempo de ejecución: se puede encontrar más información en laguía de instalación.

Los archivos de configuración devueltos incluyen la ruta completa.

Valores devueltos

Devuelve un string de archivos .ini separados por comas en caso de éxito. Cada coma va seguida por una nueva línea. Si la directiva de configuración--with-config-file-scan-dirno fué establecida y la variable de entornoPHP_INI_SCAN_DIRno es establecida,falsees retornado. Si estaba configurado y el directorio está vacío, un string vacío es retornado. Si un archivo es irreconocible, el archivo todavía se convertirá en el string retornado pero un error de PHP también resultará. Este error de PHP puede ser visto en tiempo de compilación como mientras se usaphp_ini_scanned_files().

Ejemplos

Ejemplo #1 Un ejemplo simple para enumerar los archivos ini devueltos

<?php
if ($filelist=php_ini_scanned_files()) {
if (
strlen($filelist) >0) {
$files=explode(',',$filelist);

foreach (
$filesas$file) {
echo
"<li>".trim($file) ."</li>\n";
}
}
}
?>

Ver también

  • ini_set()- Establece el valor de una directiva de configuración
  • phpinfo()- Muestra información sobre la configuración de PHP
  • php_ini_loaded_file()- Recupera la ruta de acceso al archivo php.ini cargado



php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_nameDevuelve el tipo de interfaz que hay entre PHP y el servidor

Descripción

php_sapi_name():string

Devuelve una cadena en minúsculas que describe el tipo de interfaz (la API de Servidor, SAPI) que está utilizando PHP. Por ejemplo, en PHP CLI esta cadena será "cli" mientras que en Apache podría tener varios valores diferentes dependiendo de la SAPI que se utilice. Más abajo se enumeran los posibles valores.

Valores devueltos

Devuelve el tipo de interfaz, como cadena de texto en minúsculas.

Pese a no ser una lista completa, los posibles valores incluyenaolserver,apache,apache2filter,apache2handler,caudium,cgi(hasta PHP 5.3),cgi-fcgi,cli,cli-server,continuity,embed,fpm-fcgi,isapi,litespeed,milter,nsapi,phttpd,pi3web,roxen,thttpd,tux, ywebjames.

Ejemplos

Ejemplo #1 Ejemplo dephp_sapi_name()

Este ejemplo comprueba si está la cadenacgi, ya que podría darse un nombre comocgi-fcgi.

<?php
$sapi_type
=php_sapi_name();
if (
substr($sapi_type,0,3) =='cgi') {
echo
"Está usando PHP CGI\n";
} else {
echo
"No está usando PHP CGI\n";
}
?>

Notas

Nota:Una forma alternativa

La constante de PHPPHP_SAPIcontiene el mismo valor quephp_sapi_name().

Sugerencia

Posible malentendido

Podría no ser evidente cuál es laSAPIen uso, ya que, por ejemplo, en lugar deapachepodría aparecer definida comoapache2handlero comoapache2filter.

Ver también



php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_unameDevuelve información sobre el sistema operativo en que se está ejecutando PHP

Descripción

php_uname(string$mode= "a"):string

php_uname()devuelve una descripción del sistema operativo en que se está ejecutando PHP. Esta misma información se muestra en la parte superior dephpinfo(). Para obtener solamente el nombre del sistema operativo, considere el uso de la constantePHP_OS, pero tenga en mente que la constante contendrá el sistema operativo en que PHP fuecompilado.

En algunos sistemas más antigos de UNIX, es posible que no se pueda determinar la información del SO actual en cuyo caso se revertirá mostrando el SO en que PHP fue compilado. Esto solo sucederá si la llamada a la libreria uname() no existe o no funciona.

Parámetros

mode

modees un caracter simple que define qué información es devuelta:

  • 'a': Elegida por defecto. Contiene todos los modos en la secuencia"s n r v m".
  • 's': Nombre del sistema operativo. ej.FreeBSD.
  • 'n': Nombre del Host. ej.localhost.example.com.
  • 'r': Nombre de la versión liberada. ej.5.1.2-RELEASE.
  • 'v': Información de la versión. Varia mucho entre los sistemas operativos.
  • 'm': Tipo de máquina. ej.i386.

Valores devueltos

Devuelve la descripción, como una cadena de texto.

Ejemplos

Ejemplo #1 Algúnos ejemplos dephp_uname()

<?php
echophp_uname();
echo
PHP_OS;

/* Algúnos posibles resultados:
Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
Linux

FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
FreeBSD

Windows NT XN1 5.1 build 2600
WINNT
*/

if (strtoupper(substr(PHP_OS,0,3)) ==='WIN') {
echo
'Este un servidor usando Windows!';
} else {
echo
'Este es un servidor que no usa Windows!';
}

?>

También existen algunasconstantes PHP predefinidasque pueden ser útiles, por ejemplo:

Ejemplo #2 Algunos ejemplos de las constantes relacionadas al SO

<?php
// *nix
echoDIRECTORY_SEPARATOR;// /
echoPHP_SHLIB_SUFFIX;// so
echoPATH_SEPARATOR;// :

// Win*
echoDIRECTORY_SEPARATOR;// \
echoPHP_SHLIB_SUFFIX;// dll
echoPATH_SEPARATOR;// ;
?>

Ver también



phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcreditsImprime los créditos de PHP

Descripción

phpcredits(int$flag= CREDITS_ALL):bool

Esta función imprime la lista de créditos de los desarrolladores de PHP, módulos, etc Genera los códigos HTML apropiados para insertar la información en una página.

Parámetros

flag

Para generar una página de créditos personalizada, puede utilizar el parámetroflag.

Pre-definedphpcredits()flags
namedescription
CREDITS_ALLTodos los créditos, equivalente a usar:CREDITS_DOCS+CREDITS_GENERAL+CREDITS_GROUP+CREDITS_MODULES+CREDITS_FULLPAGE. Genera una completa e independiente, página HTML con las etiquetas apropiadas.
CREDITS_DOCSLos créditos para el equipo de documentación
CREDITS_FULLPAGEPor lo general se utiliza en combinación con las otras flags. Indica que es independiente de la página HTML debe ser impreso con la información indicada por las otras flags.
CREDITS_GENERALCréditos generales: Diseño y concepto del lenguaje, autores de PHP y el módulo SAPI.
CREDITS_GROUPUna lista de los desarrolladores del núcleo.
CREDITS_MODULESUna lista de los módulos de extensión para PHP, y sus autores.
CREDITS_SAPIUna lista de los módulos de servidor API para PHP, y sus autores.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Imprimir los créditos generales

<?php
phpcredits
(CREDITS_GENERAL);
?>

Ejemplo #2 Imprimir los desarrolladores principales y el grupo de documentación

<?php
phpcredits
(CREDITS_GROUP|CREDITS_DOCS|CREDITS_FULLPAGE);
?>

Ejemplo #3 Imprimir todos los créditos

<html>
<head>
<title>Mi página de créditos</title>
</head>
<body>
<?php
// Algún código propio
phpcredits(CREDITS_ALL-CREDITS_FULLPAGE);
// algo más de código
?>
</body>
</html>

Notas

Nota:

phpcredits()genera texto plano en lugar de HTML al usar el modo CLI.

Ver también

  • phpversion()- Obtiene la versión de PHP
  • php_logo_guid()
  • phpinfo()- Muestra información sobre la configuración de PHP



phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfoMuestra información sobre la configuración de PHP

Descripción

phpinfo(int$what= INFO_ALL):bool

Muestra gran cantidad de información sobre el estado actual de PHP. Incluye información sobre las opciones de compilación y extensiones de PHP, versión de PHP, información del servidor y entorno (si se compiló como módulo), entorno PHP, versión del OS, rutas, valor de las opciones de configuración locales y generales, cabeceras HTTP y licencia de PHP.

Como cada sistema se instala diferentephpinfo()se usa comúnmente para revisaropciones de configuraciónyvariables predefinidasdisponibles en un sistema dado

phpinfo()también es una valiosa herramienta de depuración ya que contiene todos valores EGPCS (Environment, GET, POST, Cookie, Server).

Parámetros

what

El resultado de salida puede ser personalizado al pasar una o más de las siguientesconstantessumadas juntas bit a bit en el parámetro opcionalwhat. También se pueden combinar las respectivas constantes con el operador bit a bitor.

phpinfo()opciones
Nombre(constante)ValorDescripción
INFO_GENERAL1La línea de configuración, ubicación dephp.ini, fecha de compilación, servidor Web, sistema y más.
INFO_CREDITS2Créditos de PHP. Ver tambiénphpcredits().
INFO_CONFIGURATION4Valores Locales y Maestros actuales de las directivas PHP. Ver tambiénini_get().
INFO_MODULES8Módulos cargados y sus respectivos parámetros Ver tambiénget_loaded_extensions().
INFO_ENVIRONMENT16Información de las variables de entorno. Tambien disponibles en$_ENV.
INFO_VARIABLES32Muestra todas lasvariables predefinidasde EGPCS (Environment, GET, POST, Cookie, Server).
INFO_LICENSE64Información de Licencia de PHP. Ver también el» FAQ de licencia.
INFO_ALL-1Muestra toda la información anterior

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
5.5.0Los GUIDs de logos fueron reemplazados con URIs de datos, por lo que desactivar ahora expose_php no tiene efecto sobre el resutaldo de phpinfo(). Los créditos ahora también han sido embebidos en la salida misma en vez mediante enlaces.
5.2.2Se añadió la información del "Fichero de configuración cargado", mientras que anteriormente solo existía "Ruta del fichero de configuración (php.ini).

Ejemplos

Ejemplo #1 Ejemplo dephpinfo()

<?php

// Muestra toda la información, por defecto INFO_ALL
phpinfo();

// Muestra solamente la información de los módulos.
// phpinfo(8) hace exactamente lo mismo.
phpinfo(INFO_MODULES);

?>

Notas

Nota:

En versiones de PHP anteriores a la 5.5.0, las partes de la información que se muestra están deshabilidadas cuando la opción de configuraciónexpose_phpestá establecida aoff. Esto incluye los logos de PHP y Zend y los créditos.

Nota:

phpinfo()muestra texto plano en lugar de HTML cuando se utiliza en la línea de comandos.

Ver también



phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversionObtiene la versión de PHP

Descripción

phpversion(string$extension= ?):string

Devuelve una cadena que contiene la versión del analizador de PHP en ejecución o extensión.

Parámetros

extension

Un nombre de extensión opcional.

Valores devueltos

Si el parámetro opcionalextensionha sido especificado,phpversion()devuelve la versión de la extensión, ofalsesi no hay información de versión asociada o la extensión no está habilitada.

Ejemplos

Ejemplo #1phpversion()Ejemplo básico

<?php
// Imprime ejemplo 'Versión actual de PHP: 5.3.8'
echo'Versión actual de PHP: '.phpversion();

// Imprime ejemplo '2.0' o nada si la extensión no está habilitada
echophpversion('tidy');
?>

Ejemplo #2PHP_VERSION_IDEjemplo y uso

<?php
// PHP_VERSION_ID está disponible a partir de PHP 5.2.7, si nuestra
// versión es inferior a eso, entonces emular
if (!defined('PHP_VERSION_ID')) {
$version=explode('.',PHP_VERSION);

define('PHP_VERSION_ID', ($version[0] *10000+$version[1] *100+$version[2]));
}

// PHP_VERSION_ID se define como un número, donde el mayor número,
// es la versión más reciente de PHP usada. Se define tal como se utiliza la
// expresión anterior.
//
// $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
//
// Ahora, con PHP_VERSION_ID podemos comprobar las características que la versión de
// PHP pueda tener, esto no requiere el uso version_compare () cada vez que compruebe si la
// versión de PHP no es compatible con una característica.
//
// Por ejemplo, aquí podemos definir las constantes PHP_VERSION_ * que
// no están disponibles en las versiones anteriores a 5.2.7

if (PHP_VERSION_ID<50207) {
define('PHP_MAJOR_VERSION',$version[0]);
define('PHP_MINOR_VERSION',$version[1]);
define('PHP_RELEASE_VERSION',$version[2]);

// Y así sucesivamente, ...
}
?>

Notas

Nota:

Esta información también está disponible en la constante predefinidaPHP_VERSION. Más información de versión está disponible utilizando las constantesPHP_VERSION_*

Ver también



putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenvEstablece el valor de una variable de entorno

Descripción

putenv(string$assignment):bool

Agregasettingal entorno del servidor. La variable de entorno existirá únicamente durante la petición actual. Al final de la petición el entorno es recuperado a su estado original.

Parámetros

asignación

El parámetro, como p.ej."FOO=BAR"

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Definición de una variable de entorno

<?php
putenv
("UNIQID=$uniqid");
?>

Ver también

  • getenv()- Obtiene el valor de una variable de entorno
  • apache_setenv()- Establece una variable subprocess_env de Apache



restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_pathRestablece el valor de la opción de configuración include_path

Descripción

restore_include_path():void

Restablece la opción de configuracióninclude_patha su valor maestro original, tal y como se encuentre definido enphp.ini

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Ejemplo derestore_include_path()

<?php

echoget_include_path();// .:/usr/local/lib/php

set_include_path('/inc');

echo
get_include_path();// /inc

restore_include_path();

// O utilizando ini_restore()
ini_restore('include_path');

echo
get_include_path();// .:/usr/local/lib/php

?>

Ver también



set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_pathEstablece la opción de configuración include_path

Descripción

set_include_path(string$new_include_path):string

Establece la opción de configuracióninclude_pathdurante la duración del script.

Parámetros

new_include_path

El nuevo valor parainclude_path

Valores devueltos

Devuelve el valor antiguo deinclude_pathen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deset_include_path()

<?php
// Funciona a partir de PHP 4.3.0
set_include_path('/usr/lib/pear');

// Funciona en todas las versiones de PHP
ini_set('include_path','/usr/lib/pear');
?>

Ejemplo #2 Añadir a la ruta de inclusión

Haciendo uso de la constantePATH_SEPARATORes posible extender la ruta de inclusión independientemente del sistema operativo.

En este ejemplo agregamos/usr/lib/pearal final del valorinclude_pathactual.

<?php
$ruta
='/usr/lib/pear';
set_include_path(get_include_path() .PATH_SEPARATOR.$ruta);
?>

Ver también



set_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limitLimita el tiempo máximo de ejecución

Descripción

set_time_limit(int$seconds):bool

Establece el número de segundos que se permite la ejecución de un script. Si esto se alcanza, el script devuelve un error fatal. El límite predeterminado es de 30 segundos o, si es que existe, el valormax_execution_timedefinido en elphp.ini.

Cuando es llamado,set_time_limit()reinicia el contador de tiempo de espera de cero. En otras palabras, si el tiempo de espera por defecto es de 30 segundos, y 25 segundos en la ejecución del script se hace la llamadaset_time_limit(20), el script se ejecutará durante un total de 45 segundos antes de que se agote el tiempo.

Parámetros

seconds

El tiempo de ejecución máximo, en segundos. Si se pone a cero se impone sin límite de tiempo.

Valores devueltos

Devuelvetrueen caso de éxito, ofalseen caso de fallo.

Notas

Nota:

La funciónset_time_limit()y la directiva de configuraciónmax_execution_timesólo afectan el tiempo de ejecución del script mismo. Todo el tiempo dedicado a la actividad que ocurre fuera de la ejecución del script, como las llamadas al sistema usandosystem(), operaciones de secuencia, consultas a la bases de datos, etc. No se incluyen cuando se determina el tiempo máximo del script en funcionamiento. Esto no es cierto en Windows, donde el tiempo medido es real.



sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dirDevuelve la ruta del directorio para archivos temporales

Descripción

sys_get_temp_dir():string

Devuelve la ruta del directorio donde PHP almacena los archivos temporales por defecto.

Valores devueltos

Devuelve la ruta del directorio temporal.

Ejemplos

Ejemplo #1sys_get_temp_dir()example

<?php
// Crear un fichero en el temporal
// directorio de archivos utilizando sys_get_temp_dir()
$temp_file=tempnam(sys_get_temp_dir(),'Tux');

echo
$temp_file;
?>

El resultado del ejemplo sería algo similar a:

C:\Windows\Temp\TuxA318.tmp

Ver también

  • tmpfile()- Crea un archivo temporal
  • tempnam()- Crea un fichero con un nombre de fichero único



version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compareCompara dos números de versiones estandarizados de PHP

Descripción

version_compare(string$version1,string$version2,string$operator= ?):mixed

version_compare()compara dos string de números de versiones estandarizados de PHP.

Esta función, en primer lugar reemplaza los_,-y+por puntos.y las cadenas de texto de versiones y añade puntos.antes y después de cualquier código no numérico, de manera que '4.3.2RC1' sería '4.3.2.RC.1'. Después, compara cada una de las partes, de izquierda a derecha. Si alguna parte contuviera un texto especial de versión, se manejarían con el siguiente orden:cualquier texto que no se encuentre en esta lista<dev<alpha=a<beta=b<RC=rc<#<pl=p. De esta forma, no solo se pueden comparar versiones con diferentes niveles, como '4.1' y '4.1.2', sino que también se pueden comparar versiones específicas de PHP que contengan el estado de desarrollo en que se encuentran.

Parámetros

version1

Primer número de versión.

version2

Segundo número de versión.

operator

Si se especifica el tercer argumento opcionaloperator, se prueba para una relación en particular. Los posibles operadores son:<,lt,<=,le,>,gt,>=,ge,==,=,eq,!=,<>,nerespectivamente.

Este parámetro es sensible a mayúsculas, por lo que los valores debes estar en minúsculas.

Valores devueltos

Por omisión,version_compare()devuelve-1si la primera versión es inferior a la segunda,0si son iguales, y1si la segunda es inferior.

Al usar el argumento opcionaloperator, la función de volverátruesi se cumpliera la relación especificada por el operador, ofalseen caso contrario.

Ejemplos

Los siguientes ejemplos usan la constantePHP_VERSION, ya que esta contiene el valor de la versión de PHP con que se está ejecutando el código.

Ejemplo #1 Ejemplos deversion_compare()

<?php
if (version_compare(PHP_VERSION,'6.0.0') >=0) {
echo
'Soy al menos la versión 6.0.0 de PHP, mi versión: '.PHP_VERSION."\n";
}

if (
version_compare(PHP_VERSION,'5.3.0') >=0) {
echo
'Soy al menos la versión 5.3.0 de PHP, mi versión: '.PHP_VERSION."\n";
}

if (
version_compare(PHP_VERSION,'5.0.0','>=')) {
echo
'Estoy usando la versión 5 de PHP, mi versión: '.PHP_VERSION."\n";
}

if (
version_compare(PHP_VERSION,'5.0.0','<')) {
echo
'Estoy usando la versión 4 de PHP, mi versión: '.PHP_VERSION."\n";
}
?>

Notas

Nota:

La constantePHP_VERSIONalmacena la versión de PHP en uso.

Nota:

Tenga presente que las versiones preeliminares, como por ejemplo 5.3.0-dev, se las considera inferiores a la versión final (como por ejemplo 5.3.0).

Nota:

Las cadenas de versiones especiales comoalphaybetason sensibles a mayúsculas/minúsculas. Las cadenas de versiones desde fuentes arbitrarias que no se adhieren al estándar de PHP podrían necesitar ser convertidas a minúsculas mediantestrtolower()antes de llamar aversion_compare().

Ver también

  • phpversion()- Obtiene la versión de PHP
  • php_uname()- Devuelve información sobre el sistema operativo en que se está ejecutando PHP
  • function_exists()- Devuelve true si la función dada ha sido definida



zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_idDevuelve un identificador único del thread actual

Descripción

zend_thread_id():int

Esta función devuelve un identificador único del thread actual.

Valores devueltos

Devuelve thread id en formato integer.

Ejemplos

Ejemplo #1 Ejemplo dezend_thread_id()

<?php
$thread_id
=zend_thread_id();

echo
'El thread id actual es: '.$thread_id;
?>

El resultado del ejemplo sería algo similar a:

El thread actual es: 7864

Notas

Nota:

Esta función solo está disponible en PHP compilado con soporte ZTS (Zend Thread Safety) y modo debug (--enable-debug).



zend_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_versionObtiene la versión del motor Zend actual

Descripción

zend_version():string

Devuelve una cadena que contiene la versión del Motor Zend ejecutándose actualmente.

Valores devueltos

Devuelve el número de versión del Motor Zend, como una cadena.

Ejemplos

Ejemplo #1 Ejemplo dezend_version()

<?php
echo"Versión del motor Zend: ".zend_version();
?>

El resultado del ejemplo sería algo similar a:

Versión del motor Zend: 2.2.0

Ver también


Tabla de contenidos




Interactive PHP Debugger


Introducción

Implemented as a SAPI module, phpdbg can exert complete control over the environment without impacting the functionality or performance of your code.

phpdbg aims to be a lightweight, powerful, easy to use debugging platform for PHP. It offers the following features:

  • Step-Through Debugging
  • Flexible Breakpoints (Class Method, Function, File:Line, Address, Opcode)
  • Easy Access to PHP with built-in eval()
  • Userland API
  • SAPI Agnostic - Easily Integrated
  • PHP Configuration File Support
  • JIT Super Globals - Set Your Own !!
  • Optional readline Support - Comfortable Terminal Operation
  • Easy Operation - See Help :)

Command line options
OptionExample ArgumentDescription
-c-c/my/php.iniSet php.ini file to load
-d-dmemory_limit=4GSet a php.ini directive
-n Disable default php.ini
-q Suppress welcome banner
-v Enable oplog output
-b Disable color
-i-imy.initSet .phpdbginit file
-I Ignore default .phpdbginit
-O-Omy.oplogSet oplog output file
-r Run execution context
-rr Run execution context and quit after execution (not respecting breakpoints)
-e Generate extended information for debugger/profiler
-E Enable step through eval, careful!
-s-s=, -s=fooRead code to execute from stdin with an optional delimiter
-S-ScliOverride SAPI name, careful!
  

-l-l4000Setup remote console ports
-a-a192.168.0.3Setup remote console bind address
-x Enable xml output (instead of normal text output)
-p-p, -p=func, -p*Output opcodes and quit
-h Print the help overview
-V Print version number
---- arg1 arg2Use to delimit phpdbg arguments and php $argv; append any $argv argument after it



Instalación/Configuración

Tabla de contenidos


Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

phpdbg Opciones de configuración
NombrePor defectoCambiableHistorial de cambios
phpdbg.eol2PHP_INI_ALLRemoved as of PHP 8.1.0
phpdbg.path 6Removed as of PHP 8.1.0

He aquí una breve explicación de las directivas de configuración.

phpdbg.eolmixed

The kind of line ending to use for output. For setting the value, one of the string aliases must be used.

intValuestringAlias
0CRLF,crlf,DOS,dos
1LF,lf,UNIX,unix
2CR,cr,MAC,mac

phpdbg.pathstring




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

PHPDBG_VERSION(string)
PHPDBG_FILE(int)
Removed as of PHP 7.3.0.
PHPDBG_METHOD(int)
Removed as of PHP 7.3.0.
PHPDBG_LINENO(int)
Removed as of PHP 7.3.0.
PHPDBG_FUNC(int)
Removed as of PHP 7.3.0.
PHPDBG_COLOR_PROMPT(int)
PHPDBG_COLOR_NOTICE(int)
PHPDBG_COLOR_ERROR(int)



phpdbg Funciones


phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_fileInserts a breakpoint at a line in a file

Descripción

phpdbg_break_file(string$file,int$line):void

Insert a breakpoint at the givenlinein the givenfile.

Parámetros

file

The name of the file.

line

The line number.

Valores devueltos

No devuelve ningún valor.

Ver también



phpdbg_break_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_functionInserts a breakpoint at entry to a function

Descripción

phpdbg_break_function(string$function):void

Insert a breakpoint at the entry to the givenfunction.

Parámetros

function

The name of the function.

Valores devueltos

No devuelve ningún valor.

Ver también



phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_methodInserts a breakpoint at entry to a method

Descripción

phpdbg_break_method(string$class,string$method):void

Insert a breakpoint at the entry to the givenmethodof the givenclass.

Parámetros

class

The name of the class.

method

The name of the method.

Valores devueltos

No devuelve ningún valor.

Ver también



phpdbg_break_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_nextInserts a breakpoint at the next opcode

Descripción

phpdbg_break_next():void

Insert a breakpoint at the next opcode.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.

Ver también



phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clearClears all breakpoints

Descripción

phpdbg_clear():void

Clear all breakpoints that have been set, either via one of thephpdbg_break_*()functions or interactively in the console.

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.

Ver también



phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_colorSets the color of certain elements

Descripción

phpdbg_color(int$element,string$color):void

Set thecolorof the givenelement.

Parámetros

element

One of thePHPDBG_COLOR_*constants.

color

The name of the color. One ofwhite,red,green,yellow,blue,purple,cyanorblack, optionally with either a trailing-boldor-underline, for instance,white-boldorgreen-underline.

Valores devueltos

No devuelve ningún valor.

Ver también



phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog

Descripción

phpdbg_end_oplog(array$options= []):?array

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

options

Valores devueltos



phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_execAttempts to set the execution context

Descripción

phpdbg_exec(string$context):string|bool

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

context

Valores devueltos

If the execution context was set previously it is returned. If the execution context was not set previouslytrueis returned. If the request to set the context fails,falseis returned, and anE_WARNINGraised.



phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable

Descripción

phpdbg_get_executable(array$options= []):array

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

options

Valores devueltos



phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_promptSets the command prompt

Descripción

phpdbg_prompt(string$string):void

Set the command prompt to the givenstring.

Parámetros

string

The string to use as command prompt.

Valores devueltos

No devuelve ningún valor.

Ver también



phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog

Descripción

phpdbg_start_oplog():void

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.


Tabla de contenidos




runkit


Introducción

La extensión runkit proporciona medios para modificar constantes, funciones definidas por el usuario y clases definidas por el usuario. También proporciona variables superglobales personalizadas y sub-intérpretes que se pueden embeber mediante aislamiento de procesos (sandboxing).

Este paquete está hecho como una característica añadida para reemplazar al paquete» classkit. Cuando se compila con la opción--enable-runkit=classkita ./configure, exportará las definiciones de funciones y constantes compatibles con classkit.



Instalación/Configuración

Tabla de contenidos


Requerimientos

Modificar Constantes, Funciones, Clases y Métodosfunciona con todas las distribuciones de PHP 4 y PHP 5. No se necesitan requisitos especiales.

Las Superglobales Personalizadassólo están disponibles en PHP 4.2.0 o posterior.

El Aislamiento de Procesos (Sandboxing)requiere PHP 5.1.0 o posterior, o PHP 5.0.0 con un parche TSRM especial aplicado. Sin importar qué versión de PHP está en uso se debe compilar con la opción--enable-maintainer-zts. Vea el archivoREADMEen el paquete de runkit para información adicional.



Instalación

Esta extensión» PECLno se distribuye con PHP.

Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/runkit.

Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Opciones de Configuración de Runkit
NombrePor defectoCambiableHistorial de cambios
runkit.superglobal""PHP_INI_PERDIR 
runkit.internal_override"0"PHP_INI_SYSTEM 
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

runkit.superglobalstring
Una lista separada por comas de nombres de variables que van a ser tratadas como superglobales. Este valor debería estar establecido a través del archivo php.ini, pero puede funcionar en contextos de configuración por directorio dependiendo de su SAPI.

Ejemplo #1 Superglobales personalizadas con runkit.superglobal=_FOO,_BAR en php.ini

<?php
functionmostrar_valores() {
echo
"Foo es$_FOO\n";
echo
"Bar es$_BAR\n";
echo
"Baz es$_BAZ\n";
}

$_FOO='foo';
$_BAR='bar';
$_BAZ='baz';

/* Muestra foo y bar, pero no baz */
mostrar_valores();
?>
runkit.internal_overrideboolean
Habilita la capacidad de modificar/renombrar/eliminar funciones internas.



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

RUNKIT_IMPORT_FUNCTIONS(integer)
Bandera derunkit_import()que indica que las funciones normales deberían ser importadas desde el archivo especificado.
RUNKIT_IMPORT_CLASS_METHODS(integer)
Bandera derunkit_import()que indica que los métodos de clases deberían ser importados desde el archivo especificado.
RUNKIT_IMPORT_CLASS_CONSTS(integer)
Bandera derunkit_import()que indica que las constantes de clases deberían ser importadas desde el archivo especificado. Observe que esta bandera sólo tiene sentido en versiones de PHP 5.1.0 y superiores.
RUNKIT_IMPORT_CLASS_PROPS(integer)
Bandera derunkit_import()que indica que las propiedades estándar de clases deberían ser importadas desde el archivo especificado.
RUNKIT_IMPORT_CLASS_STATIC_PROPS(integer)
Bandera derunkit_import()que indica que las propiedades estáticas de clases deben ser importadas desde el fichero especificado. Disponible desde Runkit 1.0.1.
RUNKIT_IMPORT_CLASSES(integer)
Bandera derunkit_import()que representa un operador OR a nivel de bit de las constantesRUNKIT_IMPORT_CLASS_*.
RUNKIT_IMPORT_OVERRIDE(integer)
Bandera derunkit_import()que indica que si cualesquiera de las funciones, métodos, contantes o propiedades importados ya existen deberían ser reemplazados con las nuevas definiciones. Si esta bandera no está establecida, cualquier definición importada que ya exista será descartada.
RUNKIT_ACC_PUBLIC(integer)
Bandera específica de PHP 5 pararunkit_method_add()yrunkit_method_redefine()
RUNKIT_ACC_PROTECTED(integer)
Bandera específica de PHP 5 pararunkit_method_add()yrunkit_method_redefine()
RUNKIT_ACC_PRIVATE(integer)
Bandera específica de PHP 5 pararunkit_method_add()yrunkit_method_redefine()
RUNKIT_ACC_STATIC(integer)
Bandera específica de PHP 5 pararunkit_method_add()yrunkit_method_redefine(). Disponible desde Runkit 1.0.1.
CLASSKIT_ACC_PUBLIC(integer)
Bandera específica de PHP 5 paraclasskit_method_add()Sólo definida cuando la compatibilidad con classkit está habilitada.
CLASSKIT_ACC_PROTECTED(integer)
Bandera específica de PHP 5 paraclasskit_method_add()Sólo definida cuando la compatibilidad con classkit está habilitada.
CLASSKIT_ACC_PRIVATE(integer)
Bandera específica de PHP 5 paraclasskit_method_add()Sólo definida cuando la compatibilidad con classkit está habilitada.
CLASSKIT_AGGREGATE_OVERRIDE(integer)
Bandera específica de PHP 5 paraclasskit_import()Sólo definida cuando la compatibilidad con classkit está habilitada.
RUNKIT_VERSION(string)
Definida para la versión actual del paquete runkit.
CLASSKIT_VERSION(string)
Definida para la versión actual del paquete runkit. Sólo definida cuando la compatibilidad con classkit está habilitada.


Funciones de runkit


runkit_constant_add

(No version information available, might only be in Git)

runkit_constant_addSimilar a define(), excepto que también permite definir en definiciones de clase

Descripción

runkit_constant_add(string$constname,mixed$value):bool

Parámetros

constname

Nombre de la constante a declarar. Una cadena que indica la constante global, onombreclase::constnameque indica la constante de clase.

value

Valor NULL, Bool, Long, Double, String, o Resource a almacenar en la nueva constante.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



runkit_constant_redefine

(No version information available, might only be in Git)

runkit_constant_redefineRedefinir una constante ya definida

Descripción

runkit_constant_redefine(string$constname,mixed$newvalue):bool

Parámetros

constname

Constante a redefinir. Una cadena que indica la constante global, onombreclase::constnameque indica la constante de clase.

newvalue

El nuevo valor a asignar a la constante.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



runkit_constant_remove

(No version information available, might only be in Git)

runkit_constant_removeEliminar/Borrar una constante ya definida

Descripción

runkit_constant_remove(string$constname):bool

Parámetros

constname

Nombre de la constante a eliminar. Una cadena que indica la constante global, onombreclase::constnameque indica la constante de clase.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



runkit_function_add

(No version information available, might only be in Git)

runkit_function_addAñadir una nueva función, similar acreate_function()

Descripción

runkit_function_add(string$funcname,string$arglist,string$code):bool

Parámetros

funcname

Nombre de la función que va a ser creada

arglist

Lista de argumentos separados por comas

code

Código que compone la función

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Un ejemplo derunkit_function_add()

<?php
runkit_function_add
('testme','$a,$b','echo "El valor de a es $a\n"; echo "El valor de b es $b\n";');
testme(1,2);
?>

El resultado del ejemplo sería:

El valor de a es 1
El valor de b es 2

Ver también



runkit_function_copy

(No version information available, might only be in Git)

runkit_function_copyCopiar una función a un nombre de función nuevo

Descripción

runkit_function_copy(string$funcname,string$targetname):bool

Parámetros

funcname

Nombre de la función existente

targetname

Nombre de la función donde se va a copiar la definición

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Un ejemplo derunkit_function_copy()

<?php
functionoriginal() {
echo
"En una función\n";
}
runkit_function_copy('original','duplicado');
original();
duplicado();
?>

El resultado del ejemplo sería:

En una función
En una función

Ver también



runkit_function_redefine

(No version information available, might only be in Git)

runkit_function_redefineReemplazar una definición de función con una nueva implementación

Descripción

runkit_function_redefine(string$funcname,string$arglist,string$code):bool

Nota:Por defecto, sólo funciones del espacio de usuario pueden ser eliminadas, renombradas, o modificadas. Para controlar funciones internas, la opciónrunkit.internal_overrideenphp.inidebe ser habilitada.

Parámetros

funcname

Nombre de la función a redefinir

arglist

Nueva lista de argumentos a ser aceptados por la función

code

Nueva implementación de código

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Un ejemplo derunkit_function_redefine()

<?php
functiontestme() {
echo
"Implementación Original de Testme\n";
}
testme();
runkit_function_redefine('testme','','echo "Nueva Implementación de Testme\n";');
testme();
?>

El resultado del ejemplo sería:

Implementación Original de Testme
Nueva Implementación de Testme

Ver también



runkit_function_remove

(No version information available, might only be in Git)

runkit_function_removeEliminar una definición de función

Descripción

runkit_function_remove(string$funcname):bool

Nota:Por defecto, sólo funciones del espacio de usuario pueden ser eliminadas, renombradas, o modificadas. Para controlar funciones internas, la opciónrunkit.internal_overrideenphp.inidebe ser habilitada.

Parámetros

funcname

Nombre de la función a ser borrada

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



runkit_function_rename

(No version information available, might only be in Git)

runkit_function_renameCambiar el nombre de una función

Descripción

runkit_function_rename(string$funcname,string$newname):bool

Nota:Por defecto, sólo funciones del espacio de usuario pueden ser eliminadas, renombradas, o modificadas. Para controlar funciones internas, la opciónrunkit.internal_overrideenphp.inidebe ser habilitada.

Parámetros

funcname

Nombre actual de la función

newname

Nombre nuevo de la función

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



runkit_import

(No version information available, might only be in Git)

runkit_importProcesar un archivo PHP importando definiciones de funciones y clases, sobrescribiendo cuando sea apropiado

Descripción

runkit_import(string$filename,int$flags= RUNKIT_IMPORT_CLASS_METHODS):bool

Similar ainclude, sin embargo cualquier código que resida fuera de una función o clase es simplemente ignorado. Además, dependiendo del valor deflags, cualquier función o clase ya existente en el entorno de ejecución actual podría ser sobrescrito automáticamente por sus nuevas definiciones.

Parámetros

filename

El nombre de archivo desde que se va a importar las definiciones de funciones y clases

flags

Operador OR a nivel de bit de lafamilia de constantesRUNKIT_IMPORT_*.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo derunkit_import()

<?php
// importar clases completamente
runkit_import('myfile.inc',RUNKIT_IMPORT_CLASSES);

/* importar clases, aunque no importar sus propiedades estáticas
(RUNKIT_IMPORT_CLASS_STATIC_PROPS está disponible desde 1.0.1) */
runkit_import('myfile.inc',RUNKIT_IMPORT_CLASSES& ~RUNKIT_IMPORT_CLASS_STATIC_PROPS);

/* importar solamente las propiedades estáticas de las clases
(RUNKIT_IMPORT_CLASS_STATIC_PROPS está disponible desde 1.0.1) */
runkit_import('myfile.inc',RUNKIT_IMPORT_CLASS_STATIC_PROPS);
?>



runkit_method_add

(No version information available, might only be in Git)

runkit_method_addAñadir dinámicamente un nuevo método a una clase dada

Descripción

runkit_method_add(
    string$classname,
    string$methodname,
    string$args,
    string$code,
    int$flags= RUNKIT_ACC_PUBLIC
):bool

Parámetros

classname

La clase donde se va a añadir el método

methodname

El nombre del método a añadir

args

Lista de argumentos delimitados por comas para el recién creado método

code

El código a ser evaluado cuandomethodnamesea llamado

flags

El tipo de método a crear, puede serRUNKIT_ACC_PUBLIC,RUNKIT_ACC_PROTECTEDoRUNKIT_ACC_PRIVATEopcionalmente combinado mediante OR de bits conRUNKIT_ACC_STATIC(desde 1.0.1)

Nota:

Este parámetro sólo se usa a partir de PHP 5, ya que, antes de esta versión, todos los métodos eran públicos.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo derunkit_method_add()

<?php
classEjemplo{
function
foo() {
echo
"foo!\n";
}
}

// crear un objeto de Ejemplo
$e= newEjemplo();

// Añadir un nuevo método público
runkit_method_add(
'Ejemplo',
'sumar',
'$num1, $num2',
'return $num1 + $num2;',
RUNKIT_ACC_PUBLIC
);

// sumar 12 + 4
echo$e->sumar(12,4);
?>

El resultado del ejemplo sería:

16

Ver también



runkit_method_copy

(No version information available, might only be in Git)

runkit_method_copyCopia un método de una clase a otra

Descripción

runkit_method_copy(
    string$dClass,
    string$dMethod,
    string$sClass,
    string$sMethod= ?
):bool

Parámetros

dClass

Clase destino del método a copiar

dMethod

Nombre del método destino

sClass

Clase fuente del método a copiar

sMethod

Nombre del método a copiar desde la clase fuente. Si se omite este parámetro, se asume el valor dedMethod.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo derunkit_method_copy()

<?php
classFoo{
function
ejemplo() {
return
"foo!\n";
}
}

class
Bar{
// inicialmete sin métodos
}

// copiar el método ejemplo() desde la clase Foo a la clase Bar, como baz()
runkit_method_copy('Bar','baz','Foo','ejemplo');

// imprimir la función copiada
echoBar::baz();
?>

El resultado del ejemplo sería:

foo!

Ver también



runkit_method_redefine

(No version information available, might only be in Git)

runkit_method_redefineCambiar dinámicamente el código del método dado

Descripción

runkit_method_redefine(
    string$classname,
    string$methodname,
    string$args,
    string$code,
    int$flags= RUNKIT_ACC_PUBLIC
):bool

Nota:Esta función no puede ser utilizada para manipular el actual método en ejecución (o extendido).

Parámetros

classname

La clase en la que se va a redefinir el método

methodname

El nombre del método a redefinir

args

Lista de argumentos delimitados por coma para el método redefinido

code

El nuevo código a ser evaluado cuandomethodnamesea llamado

flags

El método redefinido puede serRUNKIT_ACC_PUBLIC,RUNKIT_ACC_PROTECTEDoRUNKIT_ACC_PRIVATEopcionalmente combinado mediante OR de bits conRUNKIT_ACC_STATIC(desde 1.0.1)

Nota:

Este parámetro sólo se usa a partir de PHP 5, ya que, antes de esta versión, todos los métodos eran públicos.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo derunkit_method_redefine()

<?php
classEjemplo{
function
foo() {
return
"foo!\n";
}
}

// crear un objeto de Ejemplo
$e= newEjemplo();

// imprimir Ejemplo::foo() (antes de redefinir)
echo"Antes: ".$e->foo();

// Redefinir el método 'foo'
runkit_method_redefine(
'Ejemplo',
'foo',
'',
'return "bar!\n";',
RUNKIT_ACC_PUBLIC
);

// imprimir Ejemplo::foo() (después de redefinir)
echo"Después: ".$e->foo();
?>

El resultado del ejemplo sería:

Antes: foo!
Después: bar!

Ver también



runkit_method_remove

(No version information available, might only be in Git)

runkit_method_removeEliminar dinámicamente el método dado

Descripción

runkit_method_remove(string$classname,string$methodname):bool

Nota:Esta función no puede ser utilizada para manipular el actual método en ejecución (o extendido).

Parámetros

classname

La clase en la que se va a eliminar el método

methodname

El nombre del método a eliminar

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo derunkit_method_remove()

<?php
classEjemplo{
function
foo() {
return
"foo!\n";
}

function
bar() {
return
"bar!\n";
}
}

// Eliminar el método 'foo'
runkit_method_remove(
'Ejemplo',
'foo'
);

echo
implode(' ',get_class_methods('Ejemplo'));

?>

El resultado del ejemplo sería:

bar

Ver también



runkit_method_rename

(No version information available, might only be in Git)

runkit_method_renameCambiar dinámicamente el nombre del método dado

Descripción

runkit_method_rename(string$classname,string$methodname,string$newname):bool

Nota:Esta función no puede ser utilizada para manipular el actual método en ejecución (o extendido).

Parámetros

classname

La clase en la que se renombrará el método

methodname

El nombre del método a renombrar

newname

El nombre nuevo a dar al método renombrado

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo derunkit_method_rename()

<?php
classEjemplo{
function
foo() {
return
"foo!\n";
}
}

// Renombrar el método 'foo' a 'bar'
runkit_method_rename(
'Ejemplo',
'foo',
'bar'
);

// salida de la función renombrada
echoEjemplo::bar();
?>

El resultado del ejemplo sería:

foo!

Ver también



runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_idReturn the integer object handle for given object

Descripción

runkit7_object_id(object$obj):int

This function is equivalent tospl_object_id().

This function returns a unique identifier for the object. The object id is unique for the lifetime of the object. Once the object is destroyed, its id may be reused for other objects. This behavior is similar tospl_object_hash().

Parámetros

obj

Any object.

Valores devueltos

An integer identifier that is unique for each currently existing object and is always the same for each object.

Notas

Nota:

When an object is destroyed, its id may be reused for other objects.

Ver también



runkit_superglobals

(No version information available, might only be in Git)

runkit_superglobalsDevolver el array indexado numéricamente de las superglobales registradas

Descripción

runkit_superglobals():array

Valores devueltos

Devuelve un array indexado numéricamente de las globales registradas actualmente, esto es, _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES



runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspectReturns information about the passed in value with data types, reference counts, etc

Descripción

runkit7_zval_inspect(string$value):array

Parámetros

value

The value to return the representation of

Valores devueltos

The array returned by this function contains the following elements:

  • address
  • refcount(optional)
  • is_ref(optional)
  • type

Ejemplos

Ejemplo #1runkit7_zval_inspect()example

<?php

$var
= newDateTime();
var_dump(runkit7_zval_inspect($var));

$var=1;
var_dump(runkit7_zval_inspect($var));
?>

El resultado del ejemplo sería:

array(4) {
  ["address"]=>
  string(14) "0x7f45ab21b1e0"
  ["refcount"]=>
  int(2)
  ["is_ref"]=>
  bool(false)
  ["type"]=>
  int(8)
}

array(2) {
  ["address"]=>
  string(14) "0x7f45ab21b1e0"
  ["type"]=>
  int(4)
}


Tabla de contenidos




User Operations for Zend


Introducción

The uopz - User Operations for Zend - extension exposes Zend Engine functionality normally used at compilation and execution time in order to allow modification of the internal structures that represent PHP code, and for user code to interact with the VM.

uopz supports the following activities:

  • Overloading some opcodes including ZEND_EXIT and ZEND_NEW
  • Backup and restore functions and methods
  • Renaming functions and methods
  • Copying of functions and methods
  • Deletion of functions and methods
  • Redefinition of global and class constants
  • Deletion of global and class constants
  • Runtime composition and modification of classes

Nota:

All of the activities supported are compatible with opcache

Precaución

PECL uopz 6.1.1 is not compatible with Xdebug >= 2.9.4. Later uopz versions are not compatible with Xdebug < 2.9.4.



Instalación/Configuración

Tabla de contenidos


Requerimientos

As of uopz 5.0 PHP 7.0 is required. As of uopz 5.1, PHP 7.1+ is required.



Instalación

uopz releases are hosted by PECL and the source code by» github, the easiest route to installation is the normal PECL route:» https://pecl.php.net/package/uopz.

Windows users can download prebuilt release binaries from the» PECLwebsite.

As of uopz 5.0.0 the extension must be loaded asextension. Before this version it must be loaded aszend_extension.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

uopz Opciones de configuración
NombrePor defectoCambiableHistorial de cambios
uopz.disable"0"PHP_INI_SYSTEMAvailable as of uopz 5.0.2
uopz.exit"0"PHP_INI_SYSTEMAvailable as of uopz 6.0.1
uopz.overloads"1"PHP_INI_SYSTEMAvailable as of uopz 2.0.2. Removed as of uopz 5.0.0.
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

uopz.disablebool

If enabled, uopz should stop having any effect on the engine.

uopz.exitbool

Whether to allow the execution of exit opcodes or not. This setting can be overridden during runtime by callinguopz_allow_exit().

uopz.overloadsbool

Enables the ability to useuopz_overload().

Nota:When running with OPcache enabled, it may be necessary to disable allOPcache optimizations(opcache.optimization_level=0).



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

The following opcodes are defined as constants by uopz before 5.0.0:

ZEND_EXIT(int)
Invoked by exit() and die(), receives no arguments. Return booleantrueto exit,falseto continue
ZEND_NEW(int)
Invoked by object construction, receives the class of object being created as the only argument
ZEND_THROW(int)
Invoked by the throw construct, receives the class of exception being thrown as the only argument
ZEND_FETCH_CLASS(int)
Invoked upon composure, receives the class the name of the class being fetched as the only argument
ZEND_ADD_TRAIT(int)
Invoked upon composure, receives the class the trait is being added to as the first argument, and the name of the trait as the second argument
ZEND_ADD_INTERFACE(int)
Invoked upon composure, receives the class the interface is being added to as the first argument, and the name of the interface as the second argument
ZEND_INSTANCEOF(int)
Invoked by instanceof operator, receives the object being verified as the first argument, and the name of the class which that object should be as the second argument

The following constants control the VM's behaviour after a user handler is invoked, be extremely careful! These constants are removed as of uopz 5.0.0.

ZEND_USER_OPCODE_CONTINUE(int)
Advance 1 opcode and continuue
ZEND_USER_OPCODE_ENTER(int)
Enter into new op_array without recursion
ZEND_USER_OPCODE_LEAVE(int)
Return to calling op_array within the same executor
ZEND_USER_OPCODE_DISPATCH(int)
Dispatch to original opcode handler
ZEND_USER_OPCODE_DISPATCH_TO(int)
Dispatch to a specific handler (OR'd with ZEND opcode constant)
ZEND_USER_OPCODE_RETURN(int)
Exit from executor (return from function)

The following modifiers are registered as constants by uopz

ZEND_ACC_PUBLIC(int)
Mark function as public, the default
ZEND_ACC_PROTECTED(int)
Mark function as protected
ZEND_ACC_PRIVATE(int)
Mark function as private
ZEND_ACC_STATIC(int)
Mark function as static
ZEND_ACC_FINAL(int)
Mark function as final
ZEND_ACC_ABSTRACT(int)
Mark function as abstract
ZEND_ACC_CLASS(int)
Dummy registered for consistency, the default kind of class entry. Removed as of uopz 5.0.0.
ZEND_ACC_INTERFACE(int)
Mark class as interface. Removed as of uopz 5.0.0.
ZEND_ACC_TRAIT(int)
Mark class as trait. Removed as of uopz 5.0.0.
ZEND_ACC_FETCH(int)
Used for getting flags only. Removed as of uopz 5.0.0.



Uopz Funciones


uopz_add_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_functionAdds non-existent function or method

Descripción

uopz_add_function(string$function,Closure$handler,int&$flags= ZEND_ACC_PUBLIC):bool
uopz_add_function(
    string$class,
    string$function,
    Closure$handler,
    int&$flags= ZEND_ACC_PUBLIC,
    int&$all=true
):bool

Adds a non-existent function or method.

Parámetros

class

The name of the class.

function

The name of the function or method.

handler

TheClosurethat defines the new function or method.

flags

Flags to set for the new function or method.

all

Whether all classes that descend fromclasswill also be affected.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

uopz_add_function()throws aRuntimeExceptionif the function or method to add already exists.

Ejemplos

Ejemplo #1 Basicuopz_add_function()Usage

<?php
uopz_add_function
('foo', function () {echo'bar';});
foo();
?>

El resultado del ejemplo sería:

bar

Ver también



uopz_allow_exit

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_allow_exitAllows control over disabled exit opcode

Descripción

uopz_allow_exit(bool$allow):void

By default uopz disables the exit opcode, soexit()calls are practically ignored.uopz_allow_exit()allows to control this behavior.

Parámetros

allow

Whether to allow the execution of exit opcodes or not.

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1uopz_allow_exit()example

<?php
exit(1);
echo
1;
uopz_allow_exit(true);
exit(
2);
echo
2;
?>

El resultado del ejemplo sería:

1

Notas

Precaución

OPcacheoptimizes away dead code after unconditional exit.

Ver también



uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backupBackup a function

Advertencia

Esta función ha sidoELIMINADAen PECL uopz 5.0.0.

Descripción

uopz_backup(string$function):void
uopz_backup(string$class,string$function):void

Backup a function at runtime, to be restored on shutdown

Parámetros

class

The name of the class containing the function to backup

function

The name of the function

Valores devueltos

Ejemplos

Ejemplo #1uopz_backup()example

<?php
uopz_backup
("fgets");
uopz_function("fgets", function(){
return
true;
});
var_dump(fgets());
?>

El resultado del ejemplo sería:

bool(true)


uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_composeCompose a class

Advertencia

Esta función ha sidoELIMINADAen PECL uopz 5.0.0.

Descripción

uopz_compose(
    string$name,
    array$classes,
    array$methods= ?,
    array$properties= ?,
    int$flags= ?
):void

Creates a new class of the given name that implements, extends, or uses all of the provided classes

Parámetros

name

A legal class name

classes

An array of class, interface and trait names

methods

An associative array of methods, values are either closures or [modifiers => closure]

properties

An associative array of properties, keys are names, values are modifiers

flags

Entry type, by default ZEND_ACC_CLASS

Valores devueltos

Ejemplos

Ejemplo #1uopz_compose()example

<?php
classmyClass{}
trait
myTrait{}
interface
myInterface{}

uopz_compose(
Composed::class, [
myClass::class,
myTrait::class,
myInterface::class
], [
"__construct"=> function() {
/* ... */
}
]);

var_dump(
class_uses(Composed::class),
class_parents(Composed::class),
class_implements(Composed::class));
?>

El resultado del ejemplo sería:

array(1) {
  ["myTrait"]=>
  string(7) "myTrait"
}
array(1) {
  ["myClass"]=>
  string(7) "myClass"
}
array(1) {
  ["myInterface"]=>
  string(11) "myInterface"
}


uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copyCopy a function

Advertencia

Esta función ha sidoELIMINADAen PECL uopz 5.0.0.

Descripción

uopz_copy(string$function):Closure
uopz_copy(string$class,string$function):Closure

Copy a function by name

Parámetros

class

The name of the class containing the function to copy

function

The name of the function

Valores devueltos

A Closure for the specified function

Ejemplos

Ejemplo #1uopz_copy()example

<?php
$strtotime
=uopz_copy('strtotime');

uopz_function("strtotime", function($arg1,$arg2) use($strtotime) {
/* can call original strtotime from here */
var_dump($arg1);
});

var_dump(strtotime('dummy'));
?>

El resultado del ejemplo sería:

string(5) "dummy"


uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_functionDeletes previously added function or method

Descripción

uopz_del_function(string$function):bool
uopz_del_function(string$class,string$function,int&$all=true):bool

Deletes a previously added function or method.

Parámetros

class

The name of the class.

function

The name of the function or method.

all

Whether all classes that descend fromclasswill also be affected.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

uopz_del_function()throws aRuntimeExceptionif the function or method to delete has not been added byuopz_add_function().

Ejemplos

Ejemplo #1 Basicuopz_del_function()Usage

<?php
uopz_add_function
('foo', function () {echo'bar';});
var_dump(function_exists('foo'));
uopz_del_function('foo');
var_dump(function_exists('foo'));
?>

El resultado del ejemplo sería:

bool(true)
bool(false)

Ver también



uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_deleteDelete a function

Advertencia

Esta función ha sidoELIMINADAen PECL uopz 5.0.0.

Descripción

uopz_delete(string$function):void
uopz_delete(string$class,string$function):void

Deletes a function or method

Parámetros

class

function

Valores devueltos

Ejemplos

Ejemplo #1uopz_delete()example

<?php
uopz_delete
("strlen");

echo
strlen("Hello World");
?>

El resultado del ejemplo sería algo similar a:

PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

Ejemplo #2uopz_delete()class example

<?php
classMy{
public static function
strlen($arg) {
return
strlen($arg);
}
}

uopz_delete(My::class,"strlen");

echo
My::strlen("Hello World");
?>

El resultado del ejemplo sería algo similar a:

PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10


uopz_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_extendExtend a class at runtime

Descripción

uopz_extend(string$class,string$parent):bool

Makesclassextendparent

Parámetros

class

The name of the class to extend

parent

The name of the class to inherit

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

As of PHP 7.4.0,uopz_extends()throws aRuntimeException, ifOPcacheis enabled, and the class entry of eitherclassorparent(if it is a trait) is immutable.

Ejemplos

Ejemplo #1uopz_extend()example

<?php
classA{}
class
B{}

uopz_extend(A::class,B::class);

var_dump(class_parents(A::class));
?>

El resultado del ejemplo sería:

array(1) {
  ["B"]=>
  string(1) "B"
}


uopz_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_flagsGet or set flags on function or class

Descripción

uopz_flags(string$function,int$flags= PHP_INT_MAX):int
uopz_flags(string$class,string$function,int$flags= PHP_INT_MAX):int

Get or set the flags on a class or function entry at runtime

Parámetros

class

The name of a class

function

The name of the function. Ifclassis given and an empty string is passed asfunction,uopz_flags()gets or sets the flags of the class entry.

flags

A valid set of ZEND_ACC_ flags. If omitted,uopz_flags()acts as getter.

Valores devueltos

If setting, returns old flags, else returns flags

Errores/Excepciones

As of PHP 7.4.0, if the parameterflagsis passed,uopz_flags()throws aRuntimeException, ifOPcacheis enabled, and the class entry ofclassor the function entry offunctionis immutable.

Historial de cambios

VersiónDescripción
PECL uopz 5.0.0Theflagsparameter is now optional. Formerly,ZEND_ACC_FETCHhad to be passed to useuopz_flags()as getter.

Ejemplos

Ejemplo #1uopz_flags()example

<?php
classTest{
public function
method() {
return
__CLASS__;
}
}

$flags=uopz_flags("Test","method");

var_dump((bool) (uopz_flags("Test","method") &ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test","method") &ZEND_ACC_STATIC));

var_dump(uopz_flags("Test","method",$flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));

var_dump((bool) (uopz_flags("Test","method") &ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test","method") &ZEND_ACC_STATIC));
?>

El resultado del ejemplo sería:

bool(false)
bool(false)
int(1234567890)
bool(true)
bool(true)

Ejemplo #2 "Unfinalize" a Class

<?php
final classMyClass
{
}

$flags=uopz_flags(MyClass::class,'');
uopz_flags(MyClass::class,'',$flags& ~ZEND_ACC_FINAL);
var_dump((newReflectionClass(MyClass::class))->isFinal());
?>

El resultado del ejemplo sería:

bool(false)


uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_functionCreates a function at runtime

Advertencia

Esta función ha sidoELIMINADAen PECL uopz 5.0.0.

Descripción

uopz_function(string$function,Closure$handler,int$modifiers= ?):void
uopz_function(
    string$class,
    string$function,
    Closure$handler,
    int$modifiers= ?
):void

Creates a function at runtime

Parámetros

class

The name of the class to receive the new function

function

The name of the function

handler

The Closure for the function

modifiers

The modifiers for the function, by default copied or ZEND_ACC_PUBLIC

Valores devueltos

Ejemplos

Ejemplo #1uopz_function()example

<?php
uopz_function
("my_strlen", function($arg) {
return
strlen($arg);
});
echo
my_strlen("Hello World");
?>

El resultado del ejemplo sería:

11

Ejemplo #2uopz_function()class example

<?php
classMy{}

uopz_function(My::class,"strlen", function($arg) {
return
strlen($arg);
},
ZEND_ACC_STATIC);

echo
My::strlen("Hello World");
?>

El resultado del ejemplo sería:

11


uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_statusRetrieve the last set exit status

Descripción

uopz_get_exit_status():mixed

Retrieves the last set exit status, i.e. the value passed toexit().

Parámetros

Esta función no tiene parámetros.

Valores devueltos

This function returns the last exit status, ornullifexit()has not been called.

Ejemplos

Ejemplo #1uopz_get_exit_status()example

<?php
exit(123);
echo
uopz_get_exit_status();?>

El resultado del ejemplo sería:

123

Notas

Precaución

OPcacheoptimizes away dead code after unconditional exit.

Ver también



uopz_get_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_hookGets previously set hook on function or method

Descripción

uopz_get_hook(string$function):Closure
uopz_get_hook(string$class,string$function):Closure

Gets the previously set hook on a function or method.

Parámetros

class

The name of the class.

function

The name of the function or method.

Valores devueltos

Returns the previously set hook on a function or method, ornullif no hook has been set.

Ejemplos

Ejemplo #1 Basicuopz_get_hook()Usage

<?php
functionfoo() {
echo
'foo';
}
uopz_set_hook('foo', function () {echo'bar';});
var_dump(uopz_get_hook('foo'));
?>

El resultado del ejemplo sería algo similar a:

object(Closure)#2 (0) {
}

Ver también



uopz_get_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_mockGet the current mock for a class

Descripción

uopz_get_mock(string$class):mixed

Returns the current mock forclass.

Parámetros

class

The name of the mocked class.

Valores devueltos

Either a string containing the name of the mock, or an object, ornullif no mock has been set.

Ejemplos

Ejemplo #1uopz_get_mock()example

<?php
classA{
public static function
who() {
echo
"A";
}
}

class
mockA{
public static function
who() {
echo
"mockA";
}
}

uopz_set_mock(A::class,mockA::class);
echo
uopz_get_mock(A::class);
?>

El resultado del ejemplo sería:

mockA

Ver también



uopz_get_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_propertyGets value of class or instance property

Descripción

uopz_get_property(string$class,string$property):mixed
uopz_get_property(object$instance,string$property):mixed

Gets the value of a static class property, ifclassis given, or the value of an instance property, ifinstanceis given.

Parámetros

class

The name of the class.

instance

The object instance.

property

The name of the property.

Valores devueltos

Returns the value of the class or instance property, ornullif the property is not defined.

Ejemplos

Ejemplo #1 Basicuopz_get_property()Usage

<?php
classFoo{
private static
$staticBar=10;
private
$bar=100;
}
$foo= newFoo;
var_dump(uopz_get_property('Foo','staticBar'));
var_dump(uopz_get_property($foo,'bar'));
?>

El resultado del ejemplo sería algo similar a:

int(10)
int(100)

Ver también



uopz_get_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_returnGets a previous set return value for a function

Descripción

uopz_get_return(string$function):mixed
uopz_get_return(string$class,string$function):mixed

Gets the return value of thefunctionpreviously set byuopz_set_return().

Parámetros

class

The name of the class containing the function

function

The name of the function

Valores devueltos

The return value or Closure previously set.

Ejemplos

Ejemplo #1uopz_get_return()example

<?php
uopz_set_return
("strlen",42);
echo
uopz_get_return("strlen");
?>

El resultado del ejemplo sería:

42


uopz_get_static

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_staticGets the static variables from function or method scope

Descripción

uopz_get_static(string$class,string$function):array
uopz_get_static(string$function):array

Gets the static variables from function or method scope.

Parámetros

class

The name of the class.

function

The name of the function or method.

Valores devueltos

Returns an associativearrayof variable names mapped to their current values on success, ornullif the function or method does not exist.

Ejemplos

Ejemplo #1 Basicuopz_get_static()Usage

<?php
functionfoo() {
static
$bar='baz';
}
var_dump(uopz_get_static('foo'));
?>

El resultado del ejemplo sería:

array(1) {
  ["bar"]=>
  string(3) "baz"
}

Ver también



uopz_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_implementImplements an interface at runtime

Descripción

uopz_implement(string$class,string$interface):bool

Makesclassimplementinterface

Parámetros

class

interface

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

As of PHP 7.4.0,uopz_implements()throws aRuntimeException, ifOPcacheis enabled, and the class entry ofclassis immutable.

Ejemplos

Ejemplo #1uopz_implement()example

<?php
interfacemyInterface{}

class
myClass{}

uopz_implement(myClass::class,myInterface::class);

var_dump(class_implements(myClass::class));
?>

El resultado del ejemplo sería:

array(1) {
  ["myInterface"]=>
  string(11) "myInterface"
}


uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overloadOverload a VM opcode

Advertencia

Esta función ha sidoELIMINADAen PECL uopz 5.0.0.

Descripción

uopz_overload(int$opcode,Callable$callable):void

Overloads the specifiedopcodewith the user defined function

Parámetros

opcode

A valid opcode, see constants for details of supported codes

callable

Valores devueltos

Ejemplos

Ejemplo #1uopz_overload()example

<?php
uopz_overload
(ZEND_EXIT, function(){});

exit();
echo
"Hello World";
?>

El resultado del ejemplo sería:

Hello World


uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefineRedefine a constant

Descripción

uopz_redefine(string$constant,mixed$value):bool
uopz_redefine(string$class,string$constant,mixed$value):bool

Redefines the givenconstantasvalue

Parámetros

class

The name of the class containing the constant

constant

The name of the constant

value

The new value for the constant, must be a valid type for a constant variable

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1uopz_redefine()example

<?php
define
("MY",100);

uopz_redefine("MY",1000);

echo
MY;
?>

El resultado del ejemplo sería:

1000


uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_renameRename a function at runtime

Advertencia

Esta función ha sidoELIMINADAen PECL uopz 5.0.0.

Descripción

uopz_rename(string$function,string$rename):void
uopz_rename(string$class,string$function,string$rename):void

Renamesfunctiontorename

Nota:

If both functions exist, this effectively swaps their names

Parámetros

class

The name of the class containing the function

function

The name of an existing function

rename

The new name for the function

Valores devueltos

Ejemplos

Ejemplo #1uopz_rename()example

<?php
uopz_rename
("strlen","original_strlen");

echo
original_strlen("Hello World");
?>

El resultado del ejemplo sería:

11

Ejemplo #2uopz_rename()class example

<?php
classMy{
public function
strlen($arg) {
return
strlen($arg);
}
}

uopz_rename(My::class,"strlen","original_strlen");

echo
My::original_strlen("Hello World");
?>

El resultado del ejemplo sería:

11


uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restoreRestore a previously backed up function

Advertencia

Esta función ha sidoELIMINADAen PECL uopz 5.0.0.

Descripción

uopz_restore(string$function):void
uopz_restore(string$class,string$function):void

Restore a previously backed up function

Parámetros

class

The name of the class containing the function to restore

function

The name of the function

Valores devueltos

Ejemplos

Ejemplo #1uopz_restore()example

<?php
uopz_backup
("fgets");
uopz_function("fgets", function(){
return
true;
});
var_dump(fgets());
uopz_restore('fgets');
fgets();
?>

El resultado del ejemplo sería algo similar a:

Warning: fgets() expects at least 1 parameter, 0 given in /path/to/script.php on line 8


uopz_set_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_hookSets hook to execute when entering a function or method

Descripción

uopz_set_hook(string$function,Closure$hook):bool
uopz_set_hook(string$class,string$function,Closure$hook):bool

Sets a hook to execute when entering a function or method.

Parámetros

class

The name of the class.

function

The name of the function or method.

hook

A closure to execute when entering the function or method.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Basicuopz_set_hook()Usage

<?php
functionfoo() {
echo
'foo';
}
uopz_set_hook('foo', function () {echo'bar';});
foo();
?>

El resultado del ejemplo sería:

barfoo

Ver también



uopz_set_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_mockUse mock instead of class for new objects

Descripción

uopz_set_mock(string$class,mixed$mock):void

Ifmockis a string containing the name of a class then it will be instantiated instead ofclass.mockcan also be an object.

Nota:

Only dynamic access to properties and methods will use themockobject. Static access still uses the originalclass. Seeexamplebelow.

Parámetros

class

The name of the class to be mocked.

mock

The mock to use in the form of a string containing the name of the class to use or an object. If a string is passed, it has to be the fully qualified class name. It is recommended to use the::classmagic constant in this case.

Valores devueltos

No devuelve ningún valor.

Historial de cambios

VersiónDescripción
uopz 6.0.0Mocking static members is no longer supported by this function.uopz_redefine()anduopz_set_return(), orComponerecan be used instead.

Ejemplos

Ejemplo #1uopz_set_mock()example

<?php
classA{
public function
who() {
echo
"A";
}
}

class
mockA{
public function
who() {
echo
"mockA";
}
}

uopz_set_mock(A::class,mockA::class);
(new
A)->who();
?>

El resultado del ejemplo sería:

mockA

Ejemplo #2uopz_set_mock()example

<?php
classA{
public function
who() {
echo
"A";
}
}

uopz_set_mock(A::class, new class {
public function
who() {
echo
"mockA";
}
});
(new
A)->who();
?>

El resultado del ejemplo sería:

mockA

Ejemplo #3uopz_set_mock()and static members

As of uopz 6.0.0 mocking static members is no longer supported.

<?php
classA{
const
CON='A';
public static function
who() {
echo
"A";
}
}

uopz_set_mock(A::class, new class {
const
CON='mockA';
public static function
who() {
echo
"mockA";
}
});
echo
A::CON,PHP_EOL;
A::who();
?>

El resultado del ejemplo sería:

A
A

Output of the above example in uopz 5:

mockA
mockA

Ver también



uopz_set_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_propertySets value of existing class or instance property

Descripción

uopz_set_property(string$class,string$property,mixed$value):void
uopz_set_property(object$instance,string$property,mixed$value):void

Sets the value of an existing static class property, ifclassis given, or the value of an instance property (regardless whether the instance property already exists), ifinstanceis given.

Parámetros

class

The name of the class.

instance

The object instance.

property

The name of the property.

value

The value to assign to the property.

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Basicuopz_set_property()Usage

<?php
classFoo{
private static
$staticBar;
private
$bar;
public static function
testStaticBar() {
return
self::$staticBar;
}
public function
testBar() {
return
$this->bar;
}
}
$foo= newFoo;
uopz_set_property('Foo','staticBar',10);
uopz_set_property($foo,'bar',100);
var_dump(Foo::testStaticBar());
var_dump($foo->testBar());
?>

El resultado del ejemplo sería:

int(10)

Ver también



uopz_set_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_returnProvide a return value for an existing function

Descripción

uopz_set_return(string$function,mixed$value,bool$execute=false):bool
uopz_set_return(
    string$class,
    string$function,
    mixed$value,
    bool$execute=false
):bool

Sets the return value of thefunctiontovalue. Ifvalueis a Closure andexecuteis set, the Closure will be executed in place of the original function. It is possible to call the original function from the Closure.

Nota:

This function replacesuopz_rename().

Parámetros

class

The name of the class containing the function

function

The name of an existing function

value

The value the function should return. If a Closure is provided and the execute flag is set, the Closure will be executed in place of the original function.

execute

If true, and a Closure was provided as the value, the Closure will be executed in place of the original function.

Valores devueltos

True if succeeded, false otherwise.

Ejemplos

Ejemplo #1uopz_set_return()example

<?php
uopz_set_return
("strlen",42);
echo
strlen("Banana");
?>

El resultado del ejemplo sería:

42

Ejemplo #2uopz_set_return()example

<?php
uopz_set_return
("strlen", function($str) { returnstrlen($str) *2; },true);
echo
strlen("Banana");
?>

El resultado del ejemplo sería:

12

Ejemplo #3uopz_set_return()class example

<?php
classMy{
public static function
strlen($arg) {
return
strlen($arg);
}
}
uopz_set_return(My::class,"strlen", function($str) { returnstrlen($str) *2; },true);
echo
My::strlen("Banana");
?>

El resultado del ejemplo sería:

12


uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_staticSets the static variables in function or method scope

Descripción

uopz_set_static(string$function,array$static):void
uopz_set_static(string$class,string$function,array$static):void

Sets the static variables in function or method scope.

Parámetros

class

The name of the class.

function

The name of the function or method.

static

The associativearrayof variable names mapped to their values.

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Basicuopz_set_static()Usage

<?php
functionfoo() {
static
$bar='baz';
var_dump($bar);
}
uopz_set_static('foo', ['bar'=>'qux']);
foo();
?>

El resultado del ejemplo sería:

string(3) "qux"

Ver también



uopz_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_undefineUndefine a constant

Descripción

uopz_undefine(string$constant):bool
uopz_undefine(string$class,string$constant):bool

Removes the constant at runtime

Parámetros

class

The name of the class containingconstant

constant

The name of an existing constant

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1uopz_undefine()example

<?php
define
("MY",true);

uopz_undefine("MY");

var_dump(defined("MY"));
?>

El resultado del ejemplo sería:

bool(false)


uopz_unset_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_hookRemoves previously set hook on function or method

Descripción

uopz_unset_hook(string$function):bool
uopz_unset_hook(string$class,string$function):bool

Removes the previously set hook on a function or method.

Parámetros

class

The name of the class.

function

The name of the function or method.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Basicuopz_unset_hook()Usage

<?php
functionfoo() {
echo
'foo';
}
uopz_set_hook('foo', function () {echo'bar';});
foo();
echo
PHP_EOL;
uopz_unset_hook('foo');
foo();
?>

El resultado del ejemplo sería:

barfoo
foo

Ver también



uopz_unset_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_mockUnset previously set mock

Descripción

uopz_unset_mock(string$class):void

Unsets the previously set mock forclass.

Parámetros

class

The name of the mocked class.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

ARuntimeExceptionis thrown, if no mock was previously set forclass.

Ejemplos

Ejemplo #1uopz_unset_mock()example

<?php
classA{
public static function
who() {
echo
"A";
}
}

class
mockA{
public static function
who() {
echo
"mockA";
}
}

uopz_set_mock(A::class,mockA::class);
uopz_unset_mock(A::class);
A::who();
?>

El resultado del ejemplo sería:

A

Ver también



uopz_unset_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_returnUnsets a previously set return value for a function

Descripción

uopz_unset_return(string$function):bool
uopz_unset_return(string$class,string$function):bool

Unsets the return value of thefunctionpreviously set byuopz_set_return().

Parámetros

class

The name of the class containing the function

function

The name of the function

Valores devueltos

True on success

Ejemplos

Ejemplo #1uopz_unset_return()example

<?php
uopz_set_return
("strlen",42);
$len=strlen("Banana");
uopz_unset_return("strlen");
echo
$len+strlen("Banana");
?>

El resultado del ejemplo sería:

48

Tabla de contenidos




Caché de Windows para PHP


Introducción

La Extensión de Caché de Windows para PHP es un acelerador de PHP utilizado para incrementar la velocidad de las aplicaciones de PHP que se ejecutan sobre Windows y Windows Server. Una vez que la Extensión de Caché de Windows para PHP está habilitada y cargada por el motor de PHP, las aplicaciones de PHP se podrán aprovechar de la funcionalidad sin ninguna modificación en el código.

La Extensión de Caché de Windows para PHP incluye 5 tipos diferentes de cachés. A continuación se describe el propósito de cada tipo de caché y los beneficios que ofrece.

  • Caché de opcodes de PHP- PHP es un motor de procesamiento de scripts que lee un flujo de datos de entrada que contiene texto, instrucciones de PHP, o ambas, y produce otro flujo de datos, generalmente en formato HTML. Esto significa que, en un servidor web, el motor de PHP lee, analiza, compila y ejecuta un script de PHP cada vez que es solicitado por un cliente web. Las operaciones de lectura, análisis y compilación añaden una carga adicional a la CPU del servidor web y del sistema de ficheros y por tanto afectar al rendimiento global de una aplicación web PHP. La caché de bytecodes (opcodes) de PHP se utiliza para almacenar, en memoria compartida, el script de bytecodes ya compilado de manera que pueda ser re-utilizado por el motor de PHP para ejecuciones posteriores del mismo script.

    El soporte para el almacenamiento en caché de opcode fue eliminado enWincache 2.0.0, todos los usuarios que desean tener un opcache debe utilizar la extensiónOPcacheque se incluye en PHP a partir de PHP 5.5.0.

  • Caché de Fichero- Incluso con la caché de opcodes de PHP activada, en un sistema de ficheros el motor de PHP, debe acceder a los ficheros de script. Cuando los script de PHP son almacenados en un UNC remoto de compartición de ficheros, las operaciones sobre ficheros introducen una considerable sobrecarga de rendimiento. La Extensión de Caché de Windows para PHP incluye una caché de ficheros que es utilizada para almacenar los contenidos de los ficheros de script de PHP en memoria compartida, lo que reduce la cantidad de operaciones en el sistema de ficheros realizado por el motor de PHP.

  • Caché de Resolución de Rutas de Ficheros- Los script de PHP a menudo incluyen u operan con ficheros mediante el uso de rutas relativas. Cada ruta de fichero debe ser normalizada por el motor de PHP a una ruta de fichero absoluta. Cuando una aplicación de PHP emplea muchos ficheros PHP y accede a ellos mediante rutas relativas, el tener que resolver las rutas puede afectar de manera negativa al rendimiento de la aplicación. La Extensión de Caché de Windows para PHP ofrece una caché de Resolución de Rutas de Ficheros, que se emplea para almacenar los mapeos entre las rutas relativas de ficheros y las absolutas, reduciendo por tanto la cantidad de resoluciones de rutas que el motor de PHP tiene que realizar.

  • Caché de Usuario (disponible desde la versión 1.1.0)- Los scripts de PHP pueden aprovecharse de la caché de la memoria compartida mediante el uso del API de la caché de usuario. Los objetos PHP y las variables se pueden almacenar en la caché de usuario y ser reutilizadas en posteriores peticiones. Esto se puede emplear para mejorar el rendimiento de los script de PHP y para compartir datos entre múltiples procesos de PHP.

  • Gestor de Sesión (disponible desde la versión 1.1.0)- El gestor de sesión WinCache se puede emplear para almacenar los datos de la sesión PHP en la memoria compartida. Esto evita operaciones del sistema de ficheros para leer y escribir datos de sesión, lo que mejora el rendimiento cuando se almacenan grandes cantidades de datos en la sesión de PHP.



Instalación/Configuración

Tabla de contenidos


Requerimientos

The extension is currently supported only on the following configurations:

Windows OS:

  • Windows XP SP3 with IIS 5.1 and» FastCGI Extension
  • Windows Server 2003 with IIS 6.0 and» FastCGI Extension
  • Windows Vista SP1 with IIS 7.0 and FastCGI Module
  • Windows Server 2008 with IIS 7.0 and FastCGI Module
  • Windows 7 with IIS 7.5 and FastCGI Module
  • Windows Server 2008 R2 with IIS 7.5 and FastCGI Module

PHP:

  • PHP 5.2.X, Non-thread-safe build
  • PHP 5.3 X86, Non-thread-safe VC9 build

Nota:The WinCache Extension can only be used when IIS is configured to run PHP via FastCGI.



Instalación

Esta extensión» PECLno se distribuye con PHP.

Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/wincache.

There are two packages for this extension: one package is for PHP versions 5.2.X, and the other package is for PHP 5.3.X. Select the package that is appropriate for the PHP version being used.

To install and enable the extension, follow these steps:

  1. Unpack the package into some temporary location.

  2. Copy thephp_wincache.dllfile into the PHP extensions folder. Typically this folder is called "ext" and it is located in the same folder with all PHP binary files. For example:C:\Program Files\PHP\ext.

  3. Using a text editor, open the php.ini file, which is usually located in the same folder where all PHP binary files are. For example:C:\Program Files\PHP\php.ini.

  4. Add the following line at the end of the php.ini file:extension = php_wincache.dll.

  5. Save and close thephp.inifile.

  6. Recycle the IIS Application Pools for PHP to pick up the configuration changes. To check that the extension has been enabled, create a file calledphpinfo.phpwith a PHP code that callsphpinfofunction.

  7. Save thephpinfo.phpfile in the root folder of a IIS web site that uses PHP, then open a browser and make a request to http://localhost/phpinfo.php. Search within the returned web page for a section calledwincache. If the extension is enabled, then thephpinfooutput will list the configuration settings provided by the WinCache.

Nota:Do not forget to removephpinfo.phpfile from the web site's root folder after verifying that extension has been enabled.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

La siguiente tabla enumera y explica los ajustes de configuración proporcionados por la extensión WinCache:

Opciones de configuración de WinCache
NombrePor defectoMínimoMáximoCambiableHistorial de cambios
wincache.fcenabled"1""0""1"PHP_INI_ALLDisponible a partir de WinCache 1.0.0
wincache.fcenabledfilter"NULL""NULL""NULL"PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0
wincache.fcachesize"24""5""255"PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0
wincache.fcndetect"1""0""1"PHP_INI_SYSTEMDisponible a partir de WinCache 1.1.0
wincache.maxfilesize"256""10""2048"PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0
wincache.ocenabled"1""0""1"PHP_INI_ALLDisponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0
wincache.ocenabledfilter"NULL""NULL""NULL"PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0
wincache.ocachesize"96""15""255"PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0. Eliminada a partir de 2.0.0.0
wincache.filecount"4096""1024""16384"PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0
wincache.chkinterval"30""0""300"PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0
wincache.ttlmax"1200""0""7200"PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0
wincache.enablecli001PHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0
wincache.ignorelistNULLNULLNULLPHP_INI_ALLDisponible a partir de WinCache 1.0.0
wincache.namesaltNULLNULLNULLPHP_INI_SYSTEMDisponible a partir de WinCache 1.0.0
wincache.ucenabled101PHP_INI_SYSTEMDisponible a partir de WinCache 1.1.0
wincache.ucachesize8585PHP_INI_SYSTEMDisponible a partir de WinCache 1.1.0
wincache.scachesize8585PHP_INI_SYSTEMDisponible a partir de WinCache 1.1.0
wincache.rerouteiniNULLNULLNULLPHP_INI_SYSTEMDisponible a partir de WinCache 1.2.0. Eliminada a partir de 1.3.7
wincache.reroute_enabled101PHP_INI_SYSTEM | PHP_INI_PERDIRDisponible a partir de WinCache 1.3.7
wincache.srwlocks101PHP_INI_SYSTEMDisponible a partir de WinCache 1.3.6.3. Eliminada a partir de 2.0.0.0
wincache.filemapdirNULLNULLNULLPHP_INI_SYSTEMDisponible a partir de WinCache 1.3.7.4
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

wincache.fcenabledboolean
Habilita o deshabilita la caché de ficheros.
wincache.fcenabledfilterstring
Define una lista separada por comas de identificadores de sitios web de IIS donde debería habilitarse o deshabilitarse la caché de ficheros. Esta opción funciona junto conwincache.fcenabled: siwincache.fcenabledse establece a 1, los sitios enumerados enwincache.fcenabledfiltertendrán la caché de ficheros desactivada; siwincache.fcenabledse establece a 0, los sitios enumerados enwincache.fcenabledfiltertendrán la caché activada.
wincache.fcachesizeinteger
Define el tamaño máximo de memoria (en megabytes) que se asigna a la caché de ficheros. Si el tamaño total de ficheros en caché excede el valor especificado en este ajuste, se eliminarán los ficheros más antiguos de la caché de ficheros.
wincache.fcndetectboolean
Habilita o deshabilita la detección de notificaciones de cambios en ficheros. Si está soportada la notificación de cambios en ficheros, se usará para refrescar las entradas de la caché de códigos de operación y de ficheros en cuanto los ficheros correspondientes sean modificados en un sistema de ficheros. Si la notificación de cambios en ficheros no está soportada, por ejemplo, al usar la compartición de ficheros en red, wincache hará un sondeo para los cambios en ficheros en intervalos de tiempo regulares especificados porwincache.chkinterval.
wincache.maxfilesizeinteger
Define el tamaño máximo permitido (en kilobytes) para que un fichero sea almacenado en caché. Si un fichero excede el valor especificado, no será almacenado en caché. Este ajuste se aplica solamente a la caché de ficheros.
wincache.ocenabledboolean
Habilita o deshabilita la caché de códigos de operaciones ("opcodes")Esta opción ha sido eliminada a partir de 2.0.0.0
wincache.ocenabledfilterstring
Define una lista separada por comas de identificadores de sitios web de IIS donde se debería habilitar o deshabilitar la caché de códigos de operaciones. Este ajuste funciona junto conwincache.ocenabled: siwincache.ocenabledse establece a 1, los sitios enumerados enwincache.ocenabledfiltertendrán la caché de códigos de operaciones desactivada; siwincache.ocenabledse establece a 0, los sitios enumerados enwincache.ocenabledfiltertendrán la caché de códigos de operaciones activada.Esta opción ha sido eliminada a partir de 2.0.0.0
wincache.ocachesizeinteger
Define el tamaño máximo de memoria (en megabytes) que se asigna a la caché de códigos de operaciones. Si el tamaño de dicha caché excede el valor especificado se eliminarán de la caché los códigos de operación más antiguos. Observe que el tamaño de la caché de códigos de operaciones debe ser al menos tres veces mayor que el tamaño de la caché de ficheros. Si no fuera así, el tamaño de la caché de códigos de operaciones será aumentada automáticamente.Esta opción ha sido eliminada a partir de 2.0.0.0
wincache.filecountinteger
Define cuántos ficheros se preveen que almacene en caché la extensión, para así asignar el tamaño de memoria apropiada en el momento del arranque. Si el número de ficheros excede el valor especificado, WinCache reasignará tanta memoria como sea necesaria.
wincache.chkintervalinteger
Define la frecuencia (en segundos) con que la extensión comprobará los cambios en ficheros para refrescar la caché. Si se establece a 0 se deshabilitará el refresco de la caché. Los cambios en ficheros no se verán reflejados en la caché al menos que la entrada de la caché para tales ficheros sea eliminada mediante limpieza ("scavenger"), o la provisión ("pool") de aplicaciones de IIS sea reclicada, o se llame a la función wincache_refresh_if_changed.
wincache.ttlmaxinteger
Define el tiempo máximo de vida (en segundos) para una entrada de caché que no se esté usando. Si se establece a 0, se desactivará la limpieza de la caché, por lo que las entradas en caché nunca serán eliminadas durante el tiempo de vida del proceso obrero ("worker") de IIS.
wincache.enablecliboolean
Define si la caché se habilita cuando PHP se está ejecutando en modo de línea de comandos (CLI).
wincache.ignoreliststring

Define una lista de ficheros que no deberían ser almacenados en caché por la extensión. La lista de ficheros se especifica empleando solamente nombres de ficheros, separados por el símbolo tubería - "|".

Ejemplo #1 Ejemplo dewincache.ignorelist

wincache.ignorelist = "index.php|misc.php|admin.php"

wincache.namesaltstring
Define un string que será usado al nombrar los objetos específicos de la extensión que están almacenados en la memoria compartida. Se emplea para evitar conflictos que podrían causarse si otras aplicaciones dentro de un proceso obrero de IIS intenta acceder a la memoria compartida. La longitud del sting namesalt no puede exceder de 8 caracteres.
wincache.ucenabledboolean
Habilita o deshabilita la caché de usuarios.
wincache.ucachesizeinteger
Define el tamaño máximo de memoria en megabytes que se asigna para la caché de usuario. Si el tamaño total de las variables almacenadas en la caché de usuario excede el valor especificado, se eliminarán las variables más antiguas de la caché.
wincache.scachesizeinteger
Define el tamaño máximo de memoria en megabytes que se asigna para la caché de sesión. Si el tamaño total de los datos almacenados en la caché de sesión excede el valor especificado, se eliminarán los datos más antiguos de la caché.
wincache.rerouteinistring
Especifica una ruta absoluta o relativa al fichero reroute.ini que contiene la lista de funciones de PHP cuya implementación debería ser remplazada con las funciones equivalentes de WinCache. Si se especifica una ruta relativa, se asume que sea relativa a la ubicación del fichero php-cgi.exe.Esta opción ha sido eliminada a partir de 1.3.7. Véasewincache.reroute_enabledpara una funcionalidad similar a partir de 1.3.7.
wincache.reroute_enabledboolean
Habilita o deshabilita el redireccionamiento de varias funciones de E/S de ficheros a través de la caché de ficheros.
wincache.srwlocksboolean
Habilita o deshabilita el uso de bloqueos ("locks) de lectura/escritura compartidos. La deshabilitación es útil cuando se dan condiciones de problemas de punto muerto ("deadlock") en WinCache.Esta opción ha sido eliminada a partir de 2.0.0.0
wincache.filemapdirstring
Especifica una ruta absoluta al directorio donde WinCache almacenará los ficheros temporales empleados para segmentos de memoria compartida.Este directorio debe estar en la máquina local y no en un sistema de ficheros en la red.Si no se especifica este directorio, WinCache utilizará el fichero de paginación de Windows para todos los segmentos de memoria compartida.



WinCache Statistics Script

The installation package for WinCache includes a PHP script,wincache.php, that can be used to obtain cache information and statistics.

If the WinCache extension was installed via the Microsoft Web Platform Installer, then this script is located in%SystemDrive%\Program Files\IIS\Windows Cache for PHP\. On a 64-bit version of the Windows Server operating system, the script is located in%SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP. If the extension was installed manually, then thewincache.phpwill be located in the same folder from which the content of the installation package was extracted.

To usewincache.php, copy it into a root folder of a Web site or into any subfolder. To protect the script, open it in any text editor and replace the values forUSERNAMEandPASSWORDconstants. If any other IIS authentication is enabled on the server, then follow the instructions in the comments:

Ejemplo #1 Authentication configuration forwincache.php

<?php
/**
* ======================== CONFIGURATION SETTINGS ==============================
* If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
* If you use authentication then replace the default password.
*/
define('USE_AUTHENTICATION',1);
define('USERNAME','wincache');
define('PASSWORD','wincache');

/**
* The Basic PHP authentication will work only when IIS is configured to support
* Anonymous Authentication' and nothing else. If IIS is configured to support/use
* any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
* In that case use the array below to define the names of users in your
* domain/network/workgroup which you want to grant access to.
*/
$user_allowed= array('DOMAIN\user1','DOMAIN\user2','DOMAIN\user3');

/**
* If the array contains string 'all', then all the users authenticated by IIS
* will have access to the page. Uncomment the below line and comment above line
* to grant access to all users who gets authenticated by IIS.
*/
/* $user_allowed = array('all'); */

/** ===================== END OF CONFIGURATION SETTINGS ========================== */
?>

Nota:Always protect thewincache.phpscript by using either the built-in authentication or the server's authentication mechanism. Leaving this script unprotected may compromise the security of your web application and web server.



WinCache Session Handler

The WinCache session handler (available since WinCache 1.1.0) can be used to configure PHP to store the session data in shared memory session cache. Using shared memory instead of the default file session storage helps improve performance of PHP applications that store large amount of data in session objects. Wincache session cache uses file-backed shared memory, which ensures that the session data is not lost during recycling of IIS application pools.

To configure PHP to use WinCache session handler set thephp.inisettingsession.save_handlertowincache. By default the Windows temporary file location is used for storing the session data. To change the location of the session file usesession.save_pathdirective.

Ejemplo #1 Enabling WinCache session handler

session.save_handler = wincache
session.save_path = C:\inetpub\temp\session\



WinCache Functions Reroutes

NOTE:wincache.rerouteiniwas removed as of WinCache 1.3.7.0. It has been replaced with automatic function reroutes. See:wincache.reroute_enabled.

The WinCache functions reroutes (available since WinCache 1.2.0, removed since WinCache 1.3.7.0) can be used to replace built-in PHP functions with their equivalents that are optimized for a particular purpose. WinCache extension includes Windows-optimized implementation of PHP file functions that may improve performance of PHP applications in cases when PHP has to access files on network shares. The optimized implementation is provided for the following functions:

To configure WinCache to use the functions reroutes use the filereroute.inithat is included in WinCache installation package. Copy this file into the same directory wherephp.inifile is located. After that add the wincache.rerouteini setting inphp.iniand specify an absolute or relative path to thereroute.inifile.

Ejemplo #1 Enabling WinCache functions reroutes

wincache.rerouteini = C:\PHP\reroute.ini

Nota:If WinCache functions reroutes are enabled it is recommended to increase the WinCache file cache size. This can be done by usingwincache.fcachesizesetting.

Thereroute.inifile contains the mappings between the native PHP functions and their equivalents in WinCache. Each line in the file defines a mapping by using the following syntax:

<PHP function name>:[<number of function parameters>]=<wincache function name>

The example of the file is shown below. In this example the calls to PHP functionfile_get_contents()will be replaced with calls towincache_file_get_contents()only if the number of parameters passed to the function is less than or equals to 2. Specifying the number of parameters is useful when replacement function does not handle all the function's parameters.

Ejemplo #2 Reroute.ini file content

[FunctionRerouteList]
file_exists=wincache_file_exists
file_get_contents:2=wincache_file_get_contents
readfile:2=wincache_readfile
is_readable=wincache_is_readable
is_writable=wincache_is_writable
is_writeable=wincache_is_writable
is_file=wincache_is_file
is_dir=wincache_is_dir
realpath=wincache_realpath
filesize=wincache_filesize



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Esta extensión no tiene ninguna constante definida.



Funciones de WinCache


wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfoRetrieves information about files cached in the file cache

Descripción

wincache_fcache_fileinfo(bool$summaryonly=false):array|false

Retrieves information about file cache content and its usage.

Parámetros

summaryonly

Controls whether the returned array will contain information about individual cache entries along with the file cache summary.

Valores devueltos

Array of meta data about file cache ofalseen caso de error

The array returned by this function contains the following elements:

  • total_cache_uptime- total time in seconds that the file cache has been active
  • total_file_count- total number of files that are currently in the file cache
  • total_hit_count- number of times the files have been served from the file cache
  • total_miss_count- number of times the files have not been found in the file cache
  • file_entries- an array that contains the information about all the cached files:

    • file_name- absolute file name of the cached file
    • add_time- time in seconds since the file has been added to the file cache
    • use_time- time in seconds since the file has been accessed in the file cache
    • last_check- time in seconds since the file has been checked for modifications
    • hit_count- number of times the file has been served from the cache
    • file_size- size of the cached file in bytes

Ejemplos

Ejemplo #1 Awincache_fcache_fileinfo()example

<pre>
<?php
print_r
(wincache_fcache_fileinfo());
?>
</pre>

El resultado del ejemplo sería:

Array
(   [total_cache_uptime] => 3234
    [total_file_count] => 5
    [total_hit_count] => 0
    [total_miss_count] => 1
    [file_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 1
                    [use_time] => 0
                    [last_check] => 1
                    [hit_count] => 1
                    [file_size] => 2435
                )
            [2] => Array (...iterates for each cached file)
        )
)

Ver también



wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfoRecupera información sobre el uso de memoria caché de ficheros

Descripción

wincache_fcache_meminfo():array

Recupera información sobre el uso de la memoria caché del fichero.

Valores devueltos

Array de meta datos sobre el uso de memoria caché de ficheros ofalseen caso de error

El array devuelta por esta función contiene los siguientes elementos:

  • memory_total- cantidad de memoria en bytes asignados para la caché de ficheros
  • memory_free- cantidad de memoria libre en bytes disponibles para la caché de ficheros
  • num_used_blks- número de bloques de memoria utilizados por la caché de ficheros
  • num_free_blks- número de bloques de memoria libre disponibles para la caché de ficheros
  • memory_overhead- cantidad de memoria en bytes utilizados para las estructuras internas de la caché de ficheros

Ejemplos

Ejemplo #1 Un ejemplo dewincache_fcache_meminfo()

<pre>
<?php
print_r
(wincache_fcache_meminfo());
?>
</pre>

El resultado del ejemplo sería:

Array
(
    [memory_total] => 134217728
    [memory_free] => 131339120
    [num_used_blks] => 361
    [num_free_blks] => 3
    [memory_overhead] => 5856
)

Ver también



wincache_lock

(PECL wincache >= 1.1.0)

wincache_lockObtiene un bloqueo exclusivo en una clave dada

Descripción

wincache_lock(string$key,bool$isglobal=false):bool

Obtiene un bloqueo exclusivo sobre una clave dada. La ejecución del script actual quedará en espera que se pueda obtener el bloqueo. Una vez obtenido el bloqueo, el otro script que intente solicitar dicho bloqueo utilizando la misma clave quedará en espera, hasta que el script actual libere el bloqueo conwincache_unlock().

Advertencia

El uso dewincache_lock()ywincache_unlock()puede causar bloqueos de punto muerto al ejecutar scripts de PHP en un entorno multiproceso como FastCGI. No emplear estas funciones a menos que se esté absolutamente seguro de que son necesarias. Para la mayoría de las operaciones en la caché de usuario no es necesario usar esar estas funciones.

Parámetros

key

Nombre de la clave en la cahcé para adquirir el bloqueo.

isglobal

Controla si el ámbito del bloqueo es a nivel de sistema o local. Los bloqueos locales tienen alcance para la «pool» de la aplicación en el caso de FastCGI de IIS o a todos los procesos de php que tengan el mismo identificador de proceso padre.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Empleo dewincache_lock()

<?php
$fp
=fopen("/tmp/lock.txt","r+");
if (
wincache_lock(“lock_txt_lock”)) {// realizar un bloqueo exclusivo
ftruncate($fp,0);// truncate file
fwrite($fp,"Write something here\n");
wincache_unlock(“lock_txt_lock”);// liberar el bloqueo
} else {
echo
"No se pudo obtener el bloqueo";
}
fclose($fp);
?>

Ver también



wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfoRetrieves information about files cached in the opcode cache

Descripción

wincache_ocache_fileinfo(bool$summaryonly=false):array|false

Retrieves information about opcode cache content and its usage.

Advertencia

Esta función fueELILMINADAen PHP 7.0.0.

Parámetros

summaryonly

Controls whether the returned array will contain information about individual cache entries along with the opcode cache summary.

Valores devueltos

Array of meta data about opcode cache ofalseen caso de error

The array returned by this function contains the following elements:

  • total_cache_uptime- total time in seconds that the opcode cache has been active
  • total_file_count- total number of files that are currently in the opcode cache
  • total_hit_count- number of times the compiled opcode have been served from the cache
  • total_miss_count- number of times the compiled opcode have not been found in the cache
  • is_local_cache- true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
  • file_entries- an array that contains the information about all the cached files:

    • file_name- absolute file name of the cached file
    • add_time- time in seconds since the file has been added to the opcode cache
    • use_time- time in seconds since the file has been accessed in the opcode cache
    • last_check- time in seconds since the file has been checked for modifications
    • hit_count- number of times the file has been served from the cache
    • function_count- number of functions in the cached file
    • class_count- number of classes in the cached file

Ejemplos

Ejemplo #1 Awincache_ocache_fileinfo()example

<pre>
<?php
print_r
(wincache_ocache_fileinfo());
?>
</pre>

El resultado del ejemplo sería:

Array
(
    [total_cache_uptime] => 17357
    [total_file_count] => 121
    [total_hit_count] => 36562
    [total_miss_count] => 201
    [file_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 17356
                    [use_time] => 7
                    [last_check] => 10
                    [hit_count] => 454
                    [function_count] => 0
                    [class_count] => 1
                )
            [2] => Array (...iterates for each cached file)
        )
)

Ver también



wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfoRetrieves information about opcode cache memory usage

Descripción

wincache_ocache_meminfo():array|false

Retrieves information about memory usage by opcode cache.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Array of meta data about opcode cache memory usage ofalseen caso de error

The array returned by this function contains the following elements:

  • memory_total- amount of memory in bytes allocated for the opcode cache
  • memory_free- amount of free memory in bytes available for the opcode cache
  • num_used_blks- number of memory blocks used by the opcode cache
  • num_free_blks- number of free memory blocks available for the opcode cache
  • memory_overhead- amount of memory in bytes used for the opcode cache internal structures

Advertencia

Esta función fueELILMINADAen PHP 7.0.0.

Ejemplos

Ejemplo #1 Awincache_ocache_meminfo()example

<pre>
<?php
print_r
(wincache_ocache_meminfo());
?>
</pre>

El resultado del ejemplo sería:

Array
(
    [memory_total] => 134217728
    [memory_free] => 112106972
    [num_used_blks] => 15469
    [num_free_blks] => 4
    [memory_overhead] => 247600
)

Ver también



wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changedRefreshes the cache entries for the cached files

Descripción

wincache_refresh_if_changed(array$files= NULL):bool

Refreshes the cache entries for the files, whose names were passed in the input argument. If no argument is specified then refreshes all the entries in the cache.

Parámetros

files

An array of file names for files that need to be refreshed. An absolute or relative file paths can be used.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

WinCache performs regular checks on the cached files to ensure that if any file has changed then the corresponding entry in the cache is updated. By default this check is performed every 30 seconds. If, for example, a PHP script updates another PHP script where the application's configuration settings are stored, then it may happen that after the configuration settings have been saved to a file, the application is still using old settings for some time until the cache is refreshed. In those cases it may be preferrable to refresh the cache right after the file has been changed. The following example shows how this can be done.

Ejemplo #1 Awincache_refresh_if_changed()example

<?php
$filename
='C:\inetpub\wwwroot\config.php';
$handle=fopen($filename,'w+');
if (
$handle===FALSE) die('Failed to open file '.$filename.' for writing');
fwrite($handle,'<?php $setting=something; ?>');
fclose($handle);
wincache_refresh_if_changed(array($filename));
?>

Ver también



wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfoRetrieves information about resolve file path cache

Descripción

wincache_rplist_fileinfo(bool$summaryonly=false):array|false

Retrieves information about cached mappings between relative file paths and corresponding absolute file paths.

Parámetros

summaryonly

Valores devueltos

Array of meta data about the resolve file path cache ofalseen caso de error

The array returned by this function contains the following elements:

  • total_file_count- total number of file path mappings stored in the cache
  • rplist_entries- an array that contains the information about all the cached file paths:

    • resolve_path- path to a file
    • subkey_data- corresponding absolute path to a file

Ejemplos

Ejemplo #1 Awincache_rplist_fileinfo()example

<pre>
<?php
print_r
(wincache_rplist_fileinfo());
?>
</pre>

El resultado del ejemplo sería:

Array
(
    [total_file_count] => 5
    [rplist_entries] => Array
        (
            [1] => Array
                (
                    [resolve_path] => checkcache.php
                    [subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
                )

            [2] => Array (...iterates for each cached file)
        )
)

Ver también



wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfoRetrieves information about memory usage by the resolve file path cache

Descripción

wincache_rplist_meminfo():array|false

Retrieves information about memory usage by resolve file path cache.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Array of meta data that describes memory usage by resolve file path cache. ofalseen caso de error

The array returned by this function contains the following elements:

  • memory_total- amount of memory in bytes allocated for the resolve file path cache
  • memory_free- amount of free memory in bytes available for the resolve file path cache
  • num_used_blks- number of memory blocks used by the resolve file path cache
  • num_free_blks- number of free memory blocks available for the resolve file path cache
  • memory_overhead- amount of memory in bytes used for the internal structures of resolve file path cache

Ejemplos

Ejemplo #1 Awincache_rplist_meminfo()example

<pre>
<?php
print_r
(wincache_rplist_meminfo());
?>
</pre>

El resultado del ejemplo sería:

Array
(
    [memory_total] => 9437184
    [memory_free] => 9416744
    [num_used_blks] => 23
    [num_free_blks] => 1
    [memory_overhead] => 416
)

Ver también



wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_infoRetrieves information about files cached in the session cache

Descripción

wincache_scache_info(bool$summaryonly=false):array|false

Retrieves information about session cache content and its usage.

Parámetros

summaryonly

Controls whether the returned array will contain information about individual cache entries along with the session cache summary.

Valores devueltos

Array of meta data about session cache ofalseen caso de error

The array returned by this function contains the following elements:

  • total_cache_uptime- total time in seconds that the session cache has been active
  • total_item_count- total number of elements that are currently in the session cache
  • is_local_cache- true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
  • total_hit_count- number of times the data has been served from the cache
  • total_miss_count- number of times the data has not been found in the cache
  • scache_entries- an array that contains the information about all the cached items:

    • key_name- name of the key which is used to store the data
    • value_type- type of value stored by the key
    • use_time- time in seconds since the file has been accessed in the opcode cache
    • last_check- time in seconds since the file has been checked for modifications
    • ttl_seconds- time remaining for the data to live in the cache, 0 meaning infinite
    • age_seconds- time elapsed from the time data has been added in the cache
    • hitcount- number of times data has been served from the cache

Ejemplos

Ejemplo #1 Awincache_scache_info()example

<pre>
<?php
print_r
(wincache_scache_info());
?>
</pre>

El resultado del ejemplo sería:

Array
(
    [total_cache_uptime] => 17357
    [total_file_count] => 121
    [total_hit_count] => 36562
    [total_miss_count] => 201
    [scache_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 17356
                    [use_time] => 7
                    [last_check] => 10
                    [hit_count] => 454
                    [function_count] => 0
                    [class_count] => 1
                )
            [2] => Array (...iterates for each cached file)
        )
)

Ver también



wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfoRecupera información sobre el uso de memoria caché de sesión

Descripción

wincache_scache_meminfo():array

Recupera información sobre el uso de memoria caché de la sesión.

Valores devueltos

Array de metadatos sobre el uso de la memoria caché de sesión ofalseen caso de error

El array devuelto por esta función contiene los siguientes elementos:

  • memory_total- cantidad de memoria en bytes asignado para la caché de sesión
  • memory_free- cantidad de memoria libre en bytes disponible para la caché de sesión
  • num_used_blks- número de bloques de memoria utilizados por el caché de la sesión
  • num_free_blks- número de bloques disponibles en la memoria de la caché de sesión
  • memory_overhead- cantidad de memoria en bytes utilizado para las estructuras de sesión de caché interna

Ejemplos

Ejemplo #1 Ejemplo dewincache_scache_meminfo()

<pre>
<?php
print_r
(wincache_scache_meminfo());
?>
</pre>

El resultado del ejemplo sería:

Array 
( 
    [memory_total] => 5242880 
    [memory_free] => 5215056 
    [num_used_blks] => 6 
    [num_free_blks] => 3 
    [memory_overhead] => 176
) 

Ver también



wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_addAdds a variable in user cache only if variable does not already exist in the cache

Descripción

wincache_ucache_add(string$key,mixed$value,int$ttl= 0):bool
wincache_ucache_add(array$values,mixed$unused= NULL,int$ttl= 0):bool

Adds a variable in user cache, only if this variable doesn't already exist in the cache. The added variable remains in the user cache unless its time to live expires or it is deleted by usingwincache_ucache_delete()orwincache_ucache_clear()functions.

Parámetros

key

Store the variable using thiskeyname. If a variable with same key is already present the function will fail and returnfalse.keyis case sensitive. To override the value even ifkeyis present usewincache_ucache_set()function instad.keycan also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition.

value

Value of a variable to store.Valuesupports all data types except resources, such as file handles. This paramter is ignored if first argument is an array. A general guidance is to passnullasvaluewhile using array askey. Ifvalueis an object, or an array containing objects, then the objects will be serialized. See__sleep()for details on serializing objects.

values

Associative array of keys and values.

ttl

Time for the variable to live in the cache in seconds. After the value specified inttlhas passed the stored variable will be deleted from the cache. This parameter takes a default value of0which means the variable will stay in the cache unless explicitly deleted by usingwincache_ucache_delete()orwincache_ucache_clear()functions.

Valores devueltos

Ifkeyis string, the function returnstrueon success andfalseon failure.

Ifkeyis an array, the function returns:

  • If all the name => value pairs in the array can be set, function returns an empty array;
  • If all the name => value pairs in the array cannot be set, function returnsfalse;
  • If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.

Ejemplos

Ejemplo #1wincache_ucache_add()withkeyas a string

<?php
$bar
='BAR';
var_dump(wincache_ucache_add('foo',$bar));
var_dump(wincache_ucache_add('foo',$bar));
var_dump(wincache_ucache_get('foo'));
?>

El resultado del ejemplo sería:

bool(true)
bool(false)
string(3) "BAR" 

Ejemplo #2wincache_ucache_add()withkeyas an array

<?php
$colors_array
= array('green'=>'5','Blue'=>'6','yellow'=>'7','cyan'=>'8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>

El resultado del ejemplo sería:

array(0) { } 
array(4) { 
  ["green"]=> int(-1) 
  ["Blue"]=> int(-1) 
  ["yellow"]=> int(-1) 
  ["cyan"]=> int(-1) 
} 
string(1) "6"

Ver también



wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_casCompara la variable con el valor antiguo y le asigna un nuevo valor a este

Descripción

wincache_ucache_cas(string$key,int$old_value,int$new_value):bool

Compara la variable asociada con lakeyconold_valuey si coincide entonces asigna elnew_valuea este.

Parámetros

key

El parámetrokeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.

old_value

Valor anterior de la variable apuntada porkeyen la memoria caché del usuario. El valor debe ser de tipolong, en caso contrario la función devuelvefalse.

new_value

El nuevo valor que se asigna a una variable New value which will get assigned to variable indicado por lakeysi se encuentra una coincidencia. El valor debe ser de tipolong, en caso contrario la función devolveráfalse.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Usandowincache_ucache_cas()

<?php
wincache_ucache_set
('counter',2922);
var_dump(wincache_ucache_cas('counter',2922,1));
var_dump(wincache_ucache_get('counter'));
?>

El resultado del ejemplo sería:

bool(true) 
int(1)

Ver también



wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clearElimina todo el contenido de la caché del usuario

Descripción

wincache_ucache_clear():bool

Borra o elimina todos los valores almacenados en la caché del usuario.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Usandowincache_ucache_clear()

<?php
wincache_ucache_set
('green',1);
wincache_ucache_set('red',2);
wincache_ucache_set('orange',4);
wincache_ucache_set('blue',8);
wincache_ucache_set('cyan',16);
$array1= array('green','red','orange','blue','cyan');
var_dump(wincache_ucache_get($array1));
var_dump(wincache_ucache_clear());
var_dump(wincache_ucache_get($array1));
?>

El resultado del ejemplo sería:

array(5) { ["green"]=> int(1) 
           ["red"]=> int(2) 
           ["orange"]=> int(4) 
           ["blue"]=> int(8) 
           ["cyan"]=> int(16) } 
bool(true) 
bool(false) 

Ver también



wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_decDisminuye el valor asociado a la clave

Descripción

wincache_ucache_dec(string$key,int$dec_by= 1,bool&$success= ?):mixed

Disminuye el valor asociado a lakeypor 1 o como se especifica pordec_by.

Parámetros

key

El parámetrokeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.

dec_by

El valor de la variable asociada por el que conseguirá quekeydisminuya. Si el argumento es un número de punto flotante se truncará al integer más cercano. La variable asociada con lakeydebe ser de tipolong, en caso contrario la función falla y devolveráfalse.

success

Será establecido atrueen caso de éxito yfalseen caso de error.

Valores devueltos

Devuelve el valor decrementado en caso de éxito yfalseen caso de error.

Ejemplos

Ejemplo #1 Usandowincache_ucache_dec()

<?php
wincache_ucache_set
('counter',1);
var_dump(wincache_ucache_dec('counter',2923,$success));
var_dump($success);
?>

El resultado del ejemplo sería:

int(2922) 
bool(true)

Ver también



wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_deleteElimina las variables de la memoria caché del usuario

Descripción

wincache_ucache_delete(mixed$key):bool

Elimina los elementos de la caché del usuario apuntado porkey.

Parámetros

key

El parámetrokeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.keypuede ser un array de claves.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Sikeyes un array, entonces la función devuelvefalsesi cada elemento del array no se borra de la memoria caché del usuario, en caso contrario devuelve un array que consta de todas las claves que se eliminan.

Ejemplos

Ejemplo #1 Usandowincache_ucache_delete()conkeycomo un string

<?php
wincache_ucache_set
('foo','bar');
var_dump(wincache_ucache_delete('foo'));
var_dump(wincache_ucache_exists('foo'));
?>

El resultado del ejemplo sería:

bool(true)
bool(false)

Ejemplo #2 Usingwincache_ucache_delete()conkeycomo un array

<?php
$array1
= array('green'=>'5','blue'=>'6','yellow'=>'7','cyan'=>'8');
wincache_ucache_set($array1);
$array2= array('green','blue','yellow','cyan');
var_dump(wincache_ucache_delete($array2));
?>

El resultado del ejemplo sería:

array(4) { [0]=> string(5) "green" 
           [1]=> string(4) "Blue" 
           [2]=> string(6) "yellow" 
           [3]=> string(4) "cyan" } 

Ejemplo #3 Usingwincache_ucache_delete()conkeycomo un array donde algunos elementos no se pueden eliminar

<?php
$array1
= array('green'=>'5','blue'=>'6','yellow'=>'7','cyan'=>'8');
wincache_ucache_set($array1);
$array2= array('orange','red','yellow','cyan');
var_dump(wincache_ucache_delete($array2));
?>

El resultado del ejemplo sería:

array(2) { [0]=> string(6) "yellow" 
           [1]=> string(4) "cyan" }

Ver también



wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_existsComprueba si una variable existe en la caché del usuario

Descripción

wincache_ucache_exists(string$key):bool

Comprueba si una variable con lakeyexiste en la caché de usuario o no.

Parámetros

key

Lakeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.

Valores devueltos

Devuelvetruesi la variable con lakeyexiste, en caso contrario devuelvefalse.

Ejemplos

Ejemplo #1 Usandowincache_ucache_exists()

<?php
if (!wincache_ucache_exists('green'))
wincache_ucache_set('green',1);
var_dump(wincache_ucache_exists('green'));
?>

El resultado del ejemplo sería:

bool(true)

Ver también



wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_getObtiene una variable almacenada en la caché del usuario

Descripción

wincache_ucache_get(mixed$key,bool&$success= ?):mixed

Obtiene una variable almacenada en la caché del usuario.

Parámetros

key

Lakeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.keypuede ser un array de claves. En este caso el valor de retorno será un array de valores de cada elemento en el arraykey. Si un objeto, o un array que contiene objetos, es retornado, entonces los objetos serán decodificados. Véase__wakeup()para más detalles sobre decodificar objetos.

success

Se establecerá entrueen caso de éxito yfalseen caso de error.

Valores devueltos

Sikeyes un string, la función devuelve el valor de la variable almacenada con esa clave. El parámetrosuccesses establecido atrueen caso de éxito y afalseen caso de error.

El parámetrokeyes un array, el parámetrosuccesssiempre se establece entrue. El array devuelto (pares nombre => valor) will contendrá sólo aquellos pares nombre => valor en donde la operación de obtención de caché de usuario se ha realizado correctamente. Si ninguna de las claves del array encuentran una coincidencia en la caché del usuario, un array vacío será devuelto.

Ejemplos

Ejemplo #1wincache_ucache_get()conkeycomo un string

<?php
wincache_ucache_add
('color','blue');
var_dump(wincache_ucache_get('color',$success));
var_dump($success);
?>

El resultado del ejemplo sería:

string(4) "blue"
bool(true)

Ejemplo #2wincache_ucache_get()conkeycomo un array

<?php
$array1
= array('green'=>'5','Blue'=>'6','yellow'=>'7','cyan'=>'8');
wincache_ucache_set($array1);
$array2= array('green','Blue','yellow','cyan');
var_dump(wincache_ucache_get($array2,$success));
var_dump($success);
?>

El resultado del ejemplo sería:

array(4) { ["green"]=> string(1) "5" 
           ["Blue"]=> string(1) "6" 
           ["yellow"]=> string(1) "7" 
           ["cyan"]=> string(1) "8" } 
bool(true) 

Ver también



wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_incIncrementa el valor asociado a la clave

Descripción

wincache_ucache_inc(string$key,int$inc_by= 1,bool&$success= ?):mixed

Incrementa el valor asociado a lakeypor 1 o como se especifica porinc_by.

Parámetros

key

Lakeyque se utiliza para almacenar la variable en la caché.keydistingue mayúsculas de minúsculas.

inc_by

El valor por el cual la variable asociada con lakeyserá incrementada. Si el argumento es un número de punto flotante se truncará al integer más cercano. La variable asociada con lakeydebe ser de tipolong, de lo contrario la función falla y devuelvefalse.

success

Se establecerá entrueen caso de éxito yfalseen caso de error.

Valores devueltos

Devuelve el valor incrementado en caso de éxito yfalseen caso de error.

Ejemplos

Ejemplo #1 Usandowincache_ucache_inc()

<?php
wincache_ucache_set
('counter',1);
var_dump(wincache_ucache_inc('counter',2921,$success));
var_dump($success);
?>

El resultado del ejemplo sería:

int(2922) 
bool(true)

Ver también



wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_infoRecupera información sobre los datos almacenados en la caché del usuario

Descripción

wincache_ucache_info(bool$summaryonly=false,string$key= NULL):array

Recupera información sobre los datos almacenados en la caché del usuario.

Parámetros

summaryonly

Controla si el array devuelto contiene información sobre las entradas de caché individuales junto con el resumen caché del usuario.

key

La clave de una entrada en la caché del usuario. Si se especifica a continuación, el array devuelto contendrá información sólo acerca de que la entrada de caché. Si no se especifica ysummaryonlyes establecido afalseentonces el array devuelto contendrá información sobre todas las entradas en la caché.

Valores devueltos

Array de metadatos sobre caché de usuario ofalseen caso de error

El array devuelto por esta función contiene los siguientes elementos:

  • total_cache_uptime- tiempo total en segundos que el caché de usuario ha sido activo
  • total_item_count- número total de elementos que están actualmente en la caché del usuario
  • is_local_cache- true si el caché es de metadatos para una instancia de caché local, false si los metadatos es para el la caché global
  • total_hit_count- número de veces que los datos se han servido de la memoria caché
  • total_miss_count- número de veces que los datos no se han encontrado en la caché
  • ucache_entries- un array que contiene la información sobre todos los elementos almacenados en caché:

    • key_name- nombre de la clave que se utiliza para almacenar los datos
    • value_type- tipo de valor almacenado por la clave
    • use_time- tiempo en segundos desde el fichero ha sido visitado en la caché de código de operación
    • last_check- tiempo en segundos desde el fichero ha sido chequeado para modificaciones
    • is_session- indica si los datos son una variable de sesión
    • ttl_seconds- el tiempo restante de los datos a vivir en la memoria caché, 0 significa infinito
    • age_seconds- tiempo transcurrido desde el momento que los datos han sido añadidos en la caché
    • hitcount- número de veces que los datos se han servido de la memoria caché

Ejemplos

Ejemplo #1 Usarwincache_ucache_info()

<?php
wincache_ucache_get
('green');
wincache_ucache_set('green',2922);
wincache_ucache_get('green');
wincache_ucache_get('green');
wincache_ucache_get('green');
print_r(wincache_ucache_info());
?>

El resultado del ejemplo sería:

Array 
( ["total_cache_uptime"] => int(0)
  ["is_local_cache"] => bool(false)
  ["total_item_count"] => int(1) 
  ["total_hit_count"] => int(3) 
  ["total_miss_count"] => int(1) 
  ["ucache_entries"] => Array(1) 
    ( [1] => Array(6)
      ( 
        ["key_name"] => string(5) "green"
        ["value_type"] => string(4) "long" 
        ["is_session"] => int(0) 
        ["ttl_seconds"] => int(0)
        ["age_seconds"] => int(0)
        ["hitcount"] => int(3) 
       ) 
    ) 
)

Ver también



wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfoRecupera información sobre el uso de memoria caché de usuario

Descripción

wincache_ucache_meminfo():array

Recupera información sobre el uso de memoria caché del usuario.

Valores devueltos

Array de metadatos sobre el uso de la memoria caché de usuario ofalseen caso de error

El array devuelto por esta función contiene los siguientes elementos:

  • memory_total- cantidad de memoria en bytes asignado para la caché de usuario
  • memory_free- cantidad de memoria libre en bytes disponible para la caché de usuario
  • num_used_blks- número de bloques de memoria utilizados por el caché del usuario
  • num_free_blks- número de bloques disponibles en la memoria de la caché del usuario
  • memory_overhead- cantidad de memoria en bytes utilizado para las estructuras de los usuarios de caché interna

Ejemplos

Ejemplo #1 Ejemplo dewincache_ucache_meminfo()

<pre>
<?php
print_r
(wincache_ucache_meminfo());
?>
</pre>

El resultado del ejemplo sería:

Array 
( 
    [memory_total] => 5242880 
    [memory_free] => 5215056 
    [num_used_blks] => 6 
    [num_free_blks] => 3 
    [memory_overhead] => 176
) 

Ver también



wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_setAdds a variable in user cache and overwrites a variable if it already exists in the cache

Descripción

wincache_ucache_set(mixed$key,mixed$value,int$ttl= 0):bool
wincache_ucache_set(array$values,mixed$unused= NULL,int$ttl= 0):bool

Adds a variable in user cache. Overwrites a variable if it already exists in the cache. The added or updated variable remains in the user cache unless its time to live expires or it is deleted by usingwincache_ucache_delete()orwincache_ucache_clear()functions.

Parámetros

key

Store the variable using thiskeyname. If a variable with samekeyis already present the function will overwrite the previous value with the new one.keyis case sensitive.keycan also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition.

value

Value of a variable to store.Valuesupports all data types except resources, such as file handles. This paramter is ignored if first argument is an array. A general guidance is to passnullasvaluewhile using array askey. Ifvalueis an object, or an array containing objects, then the objects will be serialized. See__sleep()for details on serializing objects.

values

Associative array of keys and values.

ttl

Time for the variable to live in the cache in seconds. After the value specified inttlhas passed the stored variable will be deleted from the cache. This parameter takes a default value of0which means the variable will stay in the cache unless explicitly deleted by usingwincache_ucache_delete()orwincache_ucache_clear()functions.

Valores devueltos

Ifkeyis string, the function returnstrueon success andfalseon failure.

Ifkeyis an array, the function returns:

  • If all the name => value pairs in the array can be set, function returns an empty array;
  • If all the name => value pairs in the array cannot be set, function returnsfalse;
  • If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.

Ejemplos

Ejemplo #1wincache_ucache_set()withkeyas a string

<?php
$bar
='BAR';
var_dump(wincache_ucache_set('foo',$bar));
var_dump(wincache_ucache_get('foo'));
$bar1='BAR1';
var_dump(wincache_ucache_set('foo',$bar1));
var_dump(wincache_ucache_get('foo'));
?>

El resultado del ejemplo sería:

bool(true)
string(3) "BAR"
bool(true)
string(3) "BAR1"

Ejemplo #2wincache_ucache_set()withkeyas an array

<?php
$colors_array
= array('green'=>'5','Blue'=>'6','yellow'=>'7','cyan'=>'8');
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>

El resultado del ejemplo sería:

array(0) {}
array(0) {}
string(1) "6"

Ver también



wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlockLibera un bloqueo exclusivo sobre una clave dada

Descripción

wincache_unlock(string$key):bool

Libera un bloqueo exclusivo que se obtuvo en una clave dada mediantewincache_lock(). Si cualquier otro proceso fue bloqueado en espera de el bloqueo en esta clave, este proceso será capaz de obtener el bloqueo.

Advertencia

Usandowincache_lock()ywincache_unlock()puede causar bloqueos al ejecutar los scripts PHP en un entorno de multi-proceso, como FastCGI. No utilice estas funciones a menos que esté absolutamente seguro de que necesitan para su uso. Para la mayoría de las operaciones en la caché de usuario no es necesario el uso de estas funciones.

Parámetros

key

Nombre de la llave en la caché para liberar el bloqueo.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Usarwincache_unlock()

<?php
$fp
=fopen("/tmp/lock.txt","r+");
if (
wincache_lock(“lock_txt_lock”)) {// hacer un bloqueo exclusivo
ftruncate($fp,0);// truncate file
fwrite($fp,"Escribir algo aquí\n");
wincache_unlock(“lock_txt_lock”);// liberar el bloqueo
} else {
echo
"No se pudo obtener el bloqueo!";
}
fclose($fp);
?>

Ver también


Tabla de contenidos



Building for Windows

Tabla de contenidos


Prerequisites

Building WinCache extension will require:

  1. PHP source code
  2. PHP build environment
  3. WinCache source code

For completing first two steps, follow the step-by-step guide for how to» build PHP on Windows.

For getting the WinCache source code follow the instructions described inDownloading PECL extensions.



Compiling and building

The following steps describe how to compile and build WinCache on Windows OS:

  1. Open a command prompt which is used to build PHP

  2. Go to the root folder where PHP sources are present

  3. Run the command:

    cscript.exe win32\build\buildconf.js

  4. Run the command:

    configure.bat --help
    The output will contain a new flag--enable-wincache.

  5. Run the command:

    configure.js [all options used to build PHP] --enable-wincache
    --enable-wincacheis the only extra option which is required to ensure that WinCache extension gets built properly. This option will build WinCache and will statically link it with PHP dll. To build WinCache extension as a stand-alone DLL use the option--enable-wincache=shared.

  6. Run the command:

    nmake



Verifying the build

The following steps describe how to verify that WinCache has been built correctly:

  1. Go to the folder where the PHP binaries are built

  2. Run the command:

    php.exe -n -d extension=php_wincache.dll -re wincache
    If WinCache has been built properly, the output of this command will list the INI directives and functions supported by WinCache.





Hierarchical Profiler


Introducción

El XHProf es un perfilador ligero jerárquico y basado en la instrumentación. Durante la fase de recopilación de datos, lleva un registro de los recuentos de llamadas e incluso métricas para los arcos en el calibre dinámico de un programa. Calcula las exclusivas métricas en la fase de reporte/procesamiento posterior, como el tiempo de espera (transcurrido), El tiempo de la CPU y el uso de la memoria. Un perfil de funciones puede ser dividido por los llamantes o llamadas. El XHProf maneja funciones recursivas detectando ciclos en la caligrafía en el propio momento de la recogida de datos y evitar los ciclos dando nombres calificados de profundidad para las invocaciones recursivas.

XHProf incluye una sencilla interfaz de usuario basada en HTML (escrita en PHP). El navegador basado en La interfaz de usuario para ver los resultados de los perfiles hace que sea fácil ver los resultados o compartirlos. con los compañeros. También se admite una vista de imagen de caligrafía.

Los informes del XHProf a menudo pueden ser útiles para entender la estructura del código siendo ejecutado. La naturaleza jerárquica de los informes puede ser utilizada para determinar, por ejemplo, qué cadena de llamadas llevó a que se llamara a una función en particular.

El XHProf permite comparar dos ejecuciones (también conocidas como informes "diff") o agregar datos de múltiples ejecuciones. Informes diferenciales y agregados, muy parecidos a los informes de una sola ejecución, ofrecen vistas "planas" y "jerárquicas" del perfil.

Se puede encontrar documentación adicional a través del sitio» facebook xhprof.



Instalación/Configuración

Tabla de contenidos


Requerimientos

Aunque no es obligatorio, xhprof incluye una interfaz que está escrito en PHP. Se utiliza para guardar y mostrar los datos reseñados en una forma utilizable, donde la observación se realiza mediante un navegador web. Por lo tanto, un servidor web PHP activado probablemente mejorará la experiencia xhprof.

También hay un "fork" (bifurcación del desarrollo) de la interfaz gráfica de usuario en» http://github.com/preinheimer/xhprof



Instalación

Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/xhprof



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Xhprof Opciones de configuración
NombrePor defectoCambiableHistorial de cambios
xhprof.output_dir""PHP_INI_ALL 

He aquí una breve explicación de las directivas de configuración.

xhprof.output_dirstring

Directorio utilizado por la aplicación por defecto de la interfaz iXHProfRuns (es decir, la clase XHProfRuns_Default) para el almacenamiento XHProf.



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

XHPROF_FLAGS_NO_BUILTINS(integer)
Se utiliza para saltar todas las funciones incorporadas (internas)
XHPROF_FLAGS_CPU(integer)
Se utiliza para agregar información de laCPUa la salida.
XHPROF_FLAGS_MEMORY(integer)
Se utiliza para agregar información de la memoria a la salida.


Ejemplos

Ejemplo #1 Ejemplo Xhprof con interfaz gráfica de usuario opcional

En este ejemplo se inicia y detiene el perfilador, a continuación, utiliza interfaz gráfica de usuario para guardar y analizar los resultados. En otras palabras, el código de la extensión se termina en la llamada axhprof_disable().

<?php
xhprof_enable
(XHPROF_FLAGS_CPU+XHPROF_FLAGS_MEMORY);

for (
$i=0;$i<=1000;$i++) {
$a=$i*$i;
}

$xhprof_data=xhprof_disable();

$XHPROF_ROOT="/tools/xhprof/";
include_once
$XHPROF_ROOT."/xhprof_lib/utils/xhprof_lib.php";
include_once
$XHPROF_ROOT."/xhprof_lib/utils/xhprof_runs.php";

$xhprof_runs= newXHProfRuns_Default();
$run_id=$xhprof_runs->save_run($xhprof_data,"xhprof_testing");

echo
"http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";

?>

El resultado del ejemplo sería algo similar a:

http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing


Xhprof Funciones


xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disableDetiene el perfilador xhprof

Descripción

xhprof_disable():array

Detiene el perfilador, y devuelve los datos xhprof de la ejecución.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Unarrayde los datos xhprof, de la ejecución.

Ejemplos

Ejemplo #1xhprof_disable()ejemplo

<?php
xhprof_enable
();

$foo=strlen("foo bar");

$xhprof_data=xhprof_disable();

print_r($xhprof_data);
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [main()==>strlen] => Array
        (
            [ct] => 1
            [wt] => 279
        )

    [main()==>xhprof_disable] => Array
        (
            [ct] => 1
            [wt] => 9
        )

    [main()] => Array
        (
            [ct] => 1
            [wt] => 610
        )

)


xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enableInicia perfil xhprof

Descripción

xhprof_enable(int$flags= 0,array$options= ?):void

Inicia perfiles xhprof.

Parámetros

flags

Flags opcionales para añadir información adicional a la creación de perfiles. Véase lasconstantes XHprofPara obtener más información acerca de estos flags, p. ej.,XHPROF_FLAGS_MEMORYpara permitir perfiles de memoria.

options

Unarrayde opciones opcionales, es decir, la opción 'ignored_functions' para pasar en las funciones que se ignoraron durante el perfilado.

Valores devueltos

null

Historial de cambios

VersiónDescripción
0.9.2El parámetro opcionaloptionsfué agregado.

Ejemplos

Ejemplo #1 Ejemplos dexhprof_enable()

<?php
// 1. tiempo transcurrido + memoria + perfiles CPU; e ignorar las funciones integradas (internas)
xhprof_enable(XHPROF_FLAGS_NO_BUILTINS|XHPROF_FLAGS_CPU|XHPROF_FLAGS_MEMORY);

// 2. perfil tiempo transcurrido; ignorando call_user_func* durante el perfilado
xhprof_enable(
0,
array(
'ignored_functions'=> array('call_user_func',
'call_user_func_array')));

// 3. tiempo transcurrido + perfil de memoria; ignorando call_user_func* durante el perfilado
xhprof_enable(
XHPROF_FLAGS_MEMORY,
array(
'ignored_functions'=> array('call_user_func',
'call_user_func_array')));
?>

Ver también



xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disableDetiene la muestra del perfilador xhprof

Descripción

xhprof_sample_disable():array

Detiene la muestra el modo perfilador xhprof, y

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Unarrayde los datos de muestra xhprof, de la ejecución.

Ejemplos

Ejemplo #1 Ejemplo dexhprof_sample_disable()

<?php
xhprof_sample_enable
();

for (
$i=0;$i<=10000;$i++) {
$a=strlen($i);
$b=$i*$a;
$c=rand();
}

$xhprof_data=xhprof_sample_disable();

print_r($xhprof_data);
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [1272935300.800000] => main()
    [1272935300.900000] => main()
)


xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enableIniciar el analisis de XHProf en modo de muestreo

Descripción

xhprof_sample_enable():void

Inicia la creación de perfiles en modo de muestra, que es una versión más ligera de peso dexhprof_enable(). El intervalo de muestreo es 0,1 segundos, y las muestras de registro de la pila de llamadas de función completa. El caso de uso principal es en gastos indirectos más bajos se requiere cuando se hace la supervisión del rendimiento y de diagnóstico.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

null

Ver también


Tabla de contenidos




Yac


Introducción

Yac (Otro caché), es un caché de datos de usuario de memoria compartida sin bloqueo, podría utilizarse para reemplazar el APC, el memcache local.



Instalación/Configuración

Tabla de contenidos


Requerimientos



Instalación

Esta extensión» PECLno se distribuye con PHP.

Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/yac.

Los binarios de Windows (ficherosDLL) para esta extensión dePECLestán disponibles en el sitio web de PECL.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Yac Opciones de configuración
NombrePor defectoCambiableHistorial de cambios
yac.compress_threshold-1PHP_INI_SYSTEM
yac.debug0PHP_INI_ALL
yac.enable1PHP_INI_SYSTEM
yac.enable_cli0PHP_INI_SYSTEM
yac.keys_memory_size4MPHP_INI_SYSTEM
yac.serializerphpPHP_INI_SYSTEM
yac.values_memory_size64MPHP_INI_SYSTEM

He aquí una breve explicación de las directivas de configuración.

yac.compress_thresholdinteger

yac.debuginteger

yac.enableinteger

yac.enable_cliinteger

yac.keys_memory_sizestring

yac.serializerstring

yac.values_memory_sizestring



Tipos de recursos




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

YAC_VERSION(string)
YAC_MAX_KEY_LEN(integer)
La longitud máxima de una clave podría ser, es de 48 bytes.
YAC_MAX_VALUE_RAW_LEN(integer)
YAC_MAX_RAW_COMPRESSED_LEN(integer)
YAC_SERIALIZER_PHP(integer)
Usa php serialize como serializador
YAC_SERIALIZER_JSON(integer)
Usa json como serializador (requrie --enable-json)
YAC_SERIALIZER_IGBINARY(integer)
Usa igbinary como serializador (require --enable-igbinary)
YAC_SERIALIZER_MSGPACK(integer)
Usa msgpack como serializador (require --enable-msgpack)
YAC_SERIALIZER(string)
Qué serializador está yac usando



La clase Yac

(PECL yac >= 1.0.0)

Introducción

Sinopsis de la Clase

classYac{
/* Propiedades */
protected$_prefix;
/* Métodos */
public__construct(string$prefix= "")
publicadd(string$keys,mixed$value,int$ttl= 0):bool
publicadd(array$key_vals):bool
publicdelete(string|array$keys,int$ttl= ?):bool
publicdump(int$$num):mixed
publicflush():bool
publicget(string|array$key,int&$cas=null):mixed
public__get(string$key):mixed
publicinfo():array
publicset(string$keys,mixed$value,int$ttl= 0):bool
publicadd(array$key_vals):bool
public__set(string$keys,mixed$value):mixed
}

Propiedades

_prefix


Yac::add

(PECL yac >= 1.0.0)

Yac::addGuardar en caché

Descripción

publicYac::add(string$keys,mixed$value,int$ttl= 0):bool
publicYac::add(array$key_vals):bool

Añadir un artículo al caché.

Parámetros

keys

stringclave

value

valor mixto, Todo tipo de valor php podría ser almacenado exceptorecurso

ttl

tiempo de expiración

Valores devueltos

bool,trueen caso de éxito,falseen caso de fallar.

Nota:

Yac::add()puede fallar si el casillero no se puede obtener, así que, si necesitas que el valor se almacene correctamente, puedes escribir códigos como:

Ejemplo #1 Asegúrate de que el artículo se almacene

while(!$yac->set("key", "vale));



Yac::__construct

(PECL yac >= 1.0.0)

Yac::__constructConstructor

Descripción

publicYac::__construct(string$prefix= "")

se utiliza un prefijo para preparar las claves, esto podría utilizarse para evitar conflictos entre aplicaciones.

Parámetros

prefix

stringprefix



Yac::delete

(PECL yac >= 1.0.0)

Yac::deleteEliminar los artículos de la memoria caché

Descripción

publicYac::delete(string|array$keys,int$ttl= ?):bool

retira los artículos de la memoria caché

Parámetros

keys

clave string, o array de multiples claves para ser removidas.

ttl

si se establece un retraso, la eliminación marcará los elementos como inválidos en ttl segundo.

Valores devueltos



Yac::dump

(PECL yac >= 1.0.0)

Yac::dumpVolcar cache

Descripción

publicYac::dump(int$$num):mixed

Volcar valores almacenados en caché

Parámetros

num

El número máximo de artículos debe ser devuelto

Valores devueltos

mixed



Yac::flush

(PECL yac >= 1.0.0)

Yac::flushLimpiar el caché

Descripción

publicYac::flush():bool

Eliminar todos los valores almacenados

Parámetros

Esta función no tiene parámetros.

Valores devueltos

bool, siempre true



Yac::get

(PECL yac >= 1.0.0)

Yac::getRecuperar los valores de caché

Descripción

publicYac::get(string|array$key,int&$cas=null):mixed

Recuperar los valores de caché

Parámetros

key

clavesstring, oarrayde multiples claves.

cas

Si no esnull, se ajustará al caso del artículo recuperado.

Valores devueltos

mixed en caso de éxito, false en caso de error



Yac::__get

(PECL yac >= 1.0.0)

Yac::__getGetter

Descripción

publicYac::__get(string$key):mixed

Recupera los valores del caché

Parámetros

key

clavestring

Valores devueltos

mixed en caso de éxito,nullen caso de error.



Yac::info

(PECL yac >= 1.0.0)

Yac::infoEstado del caché

Descripción

publicYac::info():array

Obtener el estado del sistema de caché

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve un array, consistente con: "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"



Yac::set

(PECL yac >= 1.0.0)

Yac::setGuardar en el caché

Descripción

publicYac::set(string$keys,mixed$value,int$ttl= 0):bool
publicYac::add(array$key_vals):bool

Añade un elemento a la caché, si la clave ya existe, se sobreescribe.

Parámetros

keys

clavestring

value

valor mixed, Todo tipo de valor php podría ser almacenado exceptorecurso

ttl

tiempo de expiración

Valores devueltos

el valor de sí mismo



Yac::__set

(PECL yac >= 1.0.0)

Yac::__setSetter

Descripción

publicYac::__set(string$keys,mixed$value):mixed

almacena un elemento en el caché

Parámetros

keys

clavestring

value

valor mixed, Todo tipo de valor php podría ser almacenado exceptorecurso

Valores devueltos

Siempre devuelve el valor de sí mismo


Tabla de contenidos





Manipulación de formatos de audio


Vinculaciones de audio del OpenAL


Introducción

Vinculaciones de audio independientes de la plataforma. Requiere la» biblioteca OpenAL.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

Esta extensión» PECLno se distribuye con PHP.

Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/openal.

Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.



Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración definidas enphp.ini.



Tipos de recursos

Esta extensión define cuatro tipos de recursos:Open AL(Device)- Devuelto poropenal_device_open(),Open AL(Context)- Devuelto poropenal_context_create(),Open AL(Buffer)- Devuelto poropenal_buffer_create(), yOpen AL(Source)- Devuelto poropenal_source_create().




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

ALC_FREQUENCY(integer)
Atributo de contexto
ALC_REFRESH(integer)
Atributo de contexto
ALC_SYNC(integer)
Atributo de contexto
AL_FREQUENCY(integer)
Establecer el buffer
AL_BITS(integer)
Establecer el buffer
AL_CHANNELS(integer)
Establecer el buffer
AL_SIZE(integer)
Establecer el buffer
AL_BUFFER(integer)
Establecer Fuente/Oyente (Entero)
AL_SOURCE_RELATIVE(integer)
Establecer Fuente/Oyente (Entero)
AL_SOURCE_STATE(integer)
Establecer Fuente/Oyente (Entero)
AL_PITCH(integer)
Establecer Fuente/Oyente (Flotante)
AL_GAIN(integer)
Establecer Fuente/Oyente (Flotante)
AL_MIN_GAIN(integer)
Establecer Fuente/Oyente (Flotante)
AL_MAX_GAIN(integer)
Establecer Fuente/Oyente (Flotante)
AL_MAX_DISTANCE(integer)
Establecer Fuente/Oyente (Flotante)
AL_ROLLOFF_FACTOR(integer)
Establecer Fuente/Oyente (Flotante)
AL_CONE_OUTER_GAIN(integer)
Establecer Fuente/Oyente (Flotante)
AL_CONE_INNER_ANGLE(integer)
Establecer Fuente/Oyente (Flotante)
AL_CONE_OUTER_ANGLE(integer)
Establecer Fuente/Oyente (Flotante)
AL_REFERENCE_DISTANCE(integer)
Establecer Fuente/Oyente (Flotante)
AL_POSITION(integer)
Establecer Fuente/Oyente (Vector Flotante)
AL_VELOCITY(integer)
Establecer Fuente/Oyente (Vector Flotante)
AL_DIRECTION(integer)
Establecer Fuente/Oyente (Vector Flotante)
AL_ORIENTATION(integer)
Establecer Fuente/Oyente (Vector Flotante)
AL_FORMAT_MONO8(integer)
Formato PCM
AL_FORMAT_MONO16(integer)
Formato PCM
AL_FORMAT_STEREO8(integer)
Formato PCM
AL_FORMAT_STEREO16(integer)
Formato PCM
AL_INITIAL(integer)
Fuente de Estado
AL_PLAYING(integer)
Fuente de Estado
AL_PAUSED(integer)
Fuente de Estado
AL_STOPPED(integer)
Fuente de Estado
AL_LOOPING(integer)
Fuente de Estado
AL_TRUE(integer)
Valor Booleano reconocido por OpenAL
AL_FALSE(integer)
Valor Booleano reconocido por OpenAL


Funciones de OpenAL


openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_createGenera un buffer OpenAL

Descripción

openal_buffer_create():resource

Valores devueltos

Devuelve un recursoOpen AL(Buffer)en éxito ofalseen fallo.

Ver también



openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_dataCarga un buffer con datos

Descripción

openal_buffer_data(
    resource$buffer,
    int$format,
    string$data,
    int$freq
):bool

Parámetros

buffer

Un recursoOpen AL(Buffer)(previamente creado poropenal_buffer_create()).

format

Formato dedata, uno de:AL_FORMAT_MONO8,AL_FORMAT_MONO16,AL_FORMAT_STEREO8yAL_FORMAT_STEREO16

data

Bloque de datos de audio binario en elformaty elfreqespecificado.

freq

Frecuencia dedatadados en Hz.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroyDestruye un buffer OpenAL

Descripción

openal_buffer_destroy(resource$buffer):bool

Parámetros

buffer

Un recursoOpen AL(Buffer)(previamente creado poropenal_buffer_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_getRecupera una propiedad del buffer OpenAL

Descripción

openal_buffer_get(resource$buffer,int$property):int

Parámetros

buffer

Un recursoOpen AL(Buffer)(previamente creado poropenal_buffer_create()).

property

Propiedad especifica, una de:AL_FREQUENCY,AL_BITS,AL_CHANNELSyAL_SIZE.

Valores devueltos

Devuelve un valor entero apropiada a lapropertyrequerida ofalseen caso de error.

Ver también



openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwavCarga un archivo .wav dentro de un buffer

Descripción

openal_buffer_loadwav(resource$buffer,string$wavfile):bool

Parámetros

buffer

Un recursoOpen AL(Buffer)(previamente creado poropenal_buffer_create()).

wavfile

Ruta al archivo.waven el sistema de archivolocal.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_context_create

(PECL openal >= 0.1.0)

openal_context_createCrea un contexto de procesamiento de audio

Descripción

openal_context_create(resource$device):resource

Parámetros

device

Un recursoOpen AL(Device)(previamente creado poropenal_device_open()).

Valores devueltos

Devuelve un recursoOpen AL(Context)en éxito ofalseen fallo.

Ver también



openal_context_current

(PECL openal >= 0.1.0)

openal_context_currentCrea el corriente contexto especificado

Descripción

openal_context_current(resource$context):bool

Parámetros

context

Un recursoOpen AL(Context)(previamente creado poropenal_context_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroyDestruye un contexto

Descripción

openal_context_destroy(resource$context):bool

Parámetros

context

Un recursoOpen AL(Context)(previamente creado poropenal_context_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_context_process

(PECL openal >= 0.1.0)

openal_context_processProcesa un contexto especificado

Descripción

openal_context_process(resource$context):bool

Parámetros

context

Un recursoOpen AL(Context)(previamente creado poropenal_context_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspendSuspende el contexto especificado

Descripción

openal_context_suspend(resource$context):bool

Parámetros

context

Un recursoOpen AL(Context)(previamente creado poropenal_context_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_device_close

(PECL openal >= 0.1.0)

openal_device_closeCierra un dispositivo OpenAL

Descripción

openal_device_close(resource$device):bool

Parámetros

device

Un recursoOpen AL(Device)(previamente creado poropenal_device_open()) para ser cerrado.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_device_open

(PECL openal >= 0.1.0)

openal_device_openInicia la capa de audio del OpenAL

Descripción

openal_device_open(string$device_desc= ?):resource

Parámetros

device_desc

Abre un dispositivo de audio especiado opcionalmente pordevice_desc. Sidevice_descno está especificado el primer dispositivo de audio disponible será usado.

Valores devueltos

Devuelve un recursoOpen AL(Device)en éxito ofalseen fallo.

Ver también



openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_getDevuelve una propiedad de oyente

Descripción

openal_listener_get(int$property):mixed

Parámetros

property

Propiedad para recuperar, una de:AL_GAIN(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)) yAL_ORIENTATION(array(float,float,float)).

Valores devueltos

Devuelve un flotante o un arreglo de flotantes (como apropiado) ofalseen caso de error.

Ver también



openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_setEstablece una propiedad de oyente

Descripción

openal_listener_set(int$property,mixed$setting):bool

Parámetros

property

Propiedad a establecer, una de:AL_GAIN(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)) yAL_ORIENTATION(array(float,float,float)).

setting

Valor a establecer, ya sea flotante, o un arreglo de flotantes como apropiado.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_source_create

(PECL openal >= 0.1.0)

openal_source_createGenera una fuente de recursos

Descripción

openal_source_create():resource

Valores devueltos

Devuelve un recursoOpen AL(Source)en éxito ofalseen fallo.

Ver también



openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroyDestruye una fuente de recursos

Descripción

openal_source_destroy(resource$source):bool

Parámetros

source

Un recursoOpen AL(Source)(previamente creado poropenal_source_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_source_get

(PECL openal >= 0.1.0)

openal_source_getRecupera una propiedad de una fuente del OpenAL

Descripción

openal_source_get(resource$source,int$property):mixed

Parámetros

source

Un recursoOpen AL(Source)(previamente creado poropenal_source_create()).

property

Propiedad para obtener, una de:AL_SOURCE_RELATIVE(int),AL_SOURCE_STATE(int),AL_PITCH(float),AL_GAIN(float),AL_MIN_GAIN(float),AL_MAX_GAIN(float),AL_MAX_DISTANCE(float),AL_ROLLOFF_FACTOR(float),AL_CONE_OUTER_GAIN(float),AL_CONE_INNER_ANGLE(float),AL_CONE_OUTER_ANGLE(float),AL_REFERENCE_DISTANCE(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)),AL_DIRECTION(array(float,float,float)).

Valores devueltos

Devuelve el tipo asociado con la propiedad que se recupera ofalseen caso de error.

Ver también



openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pausePausa la fuente

Descripción

openal_source_pause(resource$source):bool

Parámetros

source

Un recursoOpen AL(Source)(previamente creado poropenal_source_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_source_play

(PECL openal >= 0.1.0)

openal_source_playEmpieza la reproducción de la fuente

Descripción

openal_source_play(resource$source):bool

Parámetros

source

Un recursoOpen AL(Source)(previamente creado poropenal_source_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewindRebobina la fuente

Descripción

openal_source_rewind(resource$source):bool

Parámetros

source

Un recursoOpen AL(Source)(previamente creado poropenal_source_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_source_set

(PECL openal >= 0.1.0)

openal_source_setEstablece la propiedad de la fuente

Descripción

openal_source_set(resource$source,int$property,mixed$setting):bool

Parámetros

source

Un recursoOpen AL(Source)(previamente creado poropenal_source_create()).

property

Propiedad para establecer, una de:AL_BUFFER(OpenAL(Source)),AL_LOOPING(bool),AL_SOURCE_RELATIVE(int),AL_SOURCE_STATE(int),AL_PITCH(float),AL_GAIN(float),AL_MIN_GAIN(float),AL_MAX_GAIN(float),AL_MAX_DISTANCE(float),AL_ROLLOFF_FACTOR(float),AL_CONE_OUTER_GAIN(float),AL_CONE_INNER_ANGLE(float),AL_CONE_OUTER_ANGLE(float),AL_REFERENCE_DISTANCE(float),AL_POSITION(array(float,float,float)),AL_VELOCITY(array(float,float,float)),AL_DIRECTION(array(float,float,float)).

setting

El valor para asignar a lapropertyespecifica. Consulta la descripción de lapropertypara una descripción de el valor(es) esperando.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stopDetiene la reproducción de la fuente

Descripción

openal_source_stop(resource$source):bool

Parámetros

source

Un recursoOpen AL(Source)(previamente creado poropenal_source_create()).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



openal_stream

(PECL openal >= 0.1.0)

openal_streamEmpieza la salida de una fuente

Descripción

openal_stream(resource$source,int$format,int$rate):resource

Parámetros

source

Un recursoOpen AL(Source)(previamente creado poropenal_source_create()).

format

Formato dedata, uno de:AL_FORMAT_MONO8,AL_FORMAT_MONO16,AL_FORMAT_STEREO8yAL_FORMAT_STEREO16

rate

Frecuencias de datos para las salidas dadas en Hz.

Valores devueltos

Devuelve un recurso de salida en success ofalseen caso de error.

Ver también


Tabla de contenidos





Servicios de autenticación


Radius


Introducción

Este paquete se basa en los libradius de FreeBSD (Autenticación remota telefónica de servicio de usuario). Permite a los clientes realizar la autenticación y la contabilidad por medio de solicitudes de red a servidores remotos.

Esta extensión PECL añade soporte completo para la autenticación Radius (» RFC 2865) y contabilidad Radius (» RFC 2866). Este paquete está disponible para Unix (probado en FreeBSD y Linux) y para Windows.

Nota:

Una descripción exacta de libradius se pueden encontrar» aquí. Una descripción detallada del archivo de configuración se puede encontrar» aquí.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

Esta extensión» PECLno se distribuye con PHP.

Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/radius.

Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.



Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración definidas enphp.ini.



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Tabla de contenidos

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

RADIUS_MPPE_KEY_LEN(int)
The maximum length of MPPE keys.

RADIUS Options

Several RADIUS functions accept option flags as bitmasks. The constants representing those flags are listed below.

RADIUS_OPTION_SALT(int)

When set, this option will result in the attribute value being salt-encrypted.

RADIUS_OPTION_TAGGED(int)

When set, this option will result in the attribute value being tagged with the value of the tag parameter.



RADIUS Packet Types

RADIUS packets, whether requests or responses, always include a type. These constants are provided to make it easier to specify types when usingradius_create_request()and when comparing the result ofradius_send_request().

RADIUS_ACCESS_REQUEST(int)

An Access-Request, used to authenticate a user against a RADIUS server. Access request packets must include aRADIUS_NAS_IP_ADDRESSor aRADIUS_NAS_IDENTIFIERattribute, must also include aRADIUS_USER_PASSWORD,RADIUS_CHAP_PASSWORDor aRADIUS_STATEattribute, and should include aRADIUS_USER_NAMEattribute.

RADIUS_ACCESS_ACCEPT(int)

An Access-Accept response to an Access-Request indicating that the RADIUS server authenticated the user successfully.

RADIUS_ACCESS_REJECT(int)

An Access-Reject response to an Access-Request indicating that the RADIUS server could not authenticate the user.

RADIUS_ACCESS_CHALLENGE(int)

An Access-Challenge response to an Access-Request indicating that the RADIUS server requires further information in another Access-Request before authenticating the user.

RADIUS_ACCOUNTING_REQUEST(int)

An Accounting-Request, used to convey accounting information for a service to the RADIUS server.

RADIUS_ACCOUNTING_RESPONSE(int)

An Accounting-Response response to an Accounting-Request.

RADIUS_COA_REQUEST(int)

A CoA-Request, sent from the RADIUS server to indicate that the authorisations within the user session have changed. A response must be sent in the form of a CoA-ACK or a CoA-NAK.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_COA_ACK(int)

A CoA-ACK, sent to the RADIUS server to indicate that the user authorisations have been updated.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_COA_NAK(int)

A CoA-NAK, sent to the RADIUS server to indicate that the user authorisations could not be updated.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_DISCONNECT_REQUEST(int)

A Disconnect-Request, sent from the RADIUS server to indicate that the user session must be terminated.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_DISCONNECT_ACK(int)

A Disconnect-ACK, sent to the RADIUS server to indicate that the user session has been terminated.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_DISCONNECT_NAK(int)

A Disconnect-NAK, sent to the RADIUS server to indicate that the user session could not be terminated.

This constant is available in PECL radius 1.3.0 and later.



RADIUS Attribute Types

These constants define RADIUS attribute types that can be used withradius_put_addr(),radius_put_attr(),radius_put_int()andradius_put_string().

RADIUS_USER_NAME(int)

The User-Name attribute. The attribute value is expected to be astringcontaining the name of the user being authenticated, and can be set usingradius_put_attr().

RADIUS_USER_PASSWORD(int)

The User-Password attribute. The attribute value is expected to be astringcontaining the user's password, and can be set usingradius_put_attr(). This value will be obfuscated on transmission as described in» section 5.2 of RFC 2865.

RADIUS_CHAP_PASSWORD(int)

The Chap-Password attribute. The attribute value is expected to be astringwith the first byte containing the CHAP identifier, and the subsequent 16 bytes containing the MD5 hash of the CHAP identifier, the plaintext password and the CHAP challenge value concatenated together. Note that the CHAP challenge value should also be sent separately in aRADIUS_CHAP_CHALLENGEattribute.

Ejemplo #1 Using CHAP passwords

<?php
// Firstly, we'll create an authentication handle and request.
$radh=radius_auth_open();
radius_add_server($radh,$server,$port,$secret,3,3);
radius_create_request($radh,RADIUS_ACCESS_REQUEST);

// Assuming $password contains the plaintext password, we now:

// Generate a challenge.
$challenge=mt_rand();

// Specify a CHAP identifier.
$ident=1;

// Add the Chap-Password attribute.
$cp=md5(pack('Ca*',$ident,$password.$challenge),true);
radius_put_attr($radh,RADIUS_CHAP_PASSWORD,pack('C',$ident).$cp);

// Add the Chap-Challenge attribute.
radius_put_attr($radh,RADIUS_CHAP_CHALLENGE,$challenge);

/* From here, you would add the remaining attributes and
* call radius_send_request(). */
?>

RADIUS_NAS_IP_ADDRESS(int)

The NAS-IP-Address attribute. The attribute value is expected to the IP address of the RADIUS client encoded as anint, which can be set usingradius_put_addr().

RADIUS_NAS_PORT(int)

The NAS-Port attribute. The attribute value is expected to be the physical port of the user on the RADIUS client encoded as anint, which can be set usingradius_put_int().

RADIUS_SERVICE_TYPE(int)

The Service-Type attribute. The attribute value indicates the service type the user is requesting, and is expected to be anint, which can be set usingradius_put_int().

A number of constants are provided to represent the possible values of this attribute. They include:

  • RADIUS_LOGIN
  • RADIUS_FRAMED
  • RADIUS_CALLBACK_LOGIN
  • RADIUS_CALLBACK_FRAMED
  • RADIUS_OUTBOUND
  • RADIUS_ADMINISTRATIVE
  • RADIUS_NAS_PROMPT
  • RADIUS_AUTHENTICATE_ONLY
  • RADIUS_CALLBACK_NAS_PROMPT

RADIUS_FRAMED_PROTOCOL(int)

The Framed-Protocol attribute. The attribute value is expected to be anintindicating the framing to be used for framed access, and can be set usingradius_put_int(). The possible attribute values include these constants:

  • RADIUS_PPP
  • RADIUS_SLIP
  • RADIUS_ARAP
  • RADIUS_GANDALF
  • RADIUS_XYLOGICS

RADIUS_FRAMED_IP_ADDRESS(int)

The Framed-IP-Address attribute. The attribute value is expected to be the address of the user's network encoded as anint, which can be set usingradius_put_addr()and retrieved usingradius_cvt_addr().

RADIUS_FRAMED_IP_NETMASK(int)

The Framed-IP-Netmask attribute. The attribute value is expected to be the netmask of the user's network encoded as anint, which can be set usingradius_put_addr()and retrieved usingradius_cvt_addr().

RADIUS_FRAMED_ROUTING(int)

The Framed-Routing attribute. The attribute value is expected to be anintindicating the routing method for the user, which can be set usingradius_put_int().

Possible values include:

  • 0: No routing
  • 1: Send routing packets
  • 2: Listen for routing packets
  • 3: Send and listen

RADIUS_FILTER_ID(int)

The Filter-ID attribute. The attribute value is expected to be an implementation-specific, human-readablestringof filters, which can be set usingradius_put_attr().

RADIUS_FRAMED_MTU(int)

The Framed-MTU attribute. The attribute value is expected to be anintindicating the MTU to be configured for the user, and can be set usingradius_put_int().

RADIUS_FRAMED_COMPRESSION(int)

The Framed-Compression attribute. The attribute value is expected to be anintindicating the compression protocol to be used, and can be set usingradius_put_int(). Possible values include these constants:

  • RADIUS_COMP_NONE: No compression
  • RADIUS_COMP_VJ: VJ TCP/IP header compression
  • RADIUS_COMP_IPXHDR: IPX header compression
  • RADIUS_COMP_STAC_LZS: Stac-LZS compression (added in PECL radius 1.3.0b2)

RADIUS_LOGIN_IP_HOST(int)

The Login-IP-Host attribute. The attribute value is expected to the IP address to connect the user to, encoded as anint, which can be set usingradius_put_addr().

RADIUS_LOGIN_SERVICE(int)

The Login-Service attribute. The attribute value is anintindicating the service to connect the user to on the login host. The value can be converted to a PHP integer viaradius_cvt_int().

RADIUS_LOGIN_TCP_PORT(int)

The Login-TCP-Port attribute. The attribute value is anintindicating the port to connect the user to on the login host. The value can be converted to a PHP integer viaradius_cvt_int().

RADIUS_REPLY_MESSAGE(int)

The Reply-Message attribute. The attribute value is astringcontaining text that may be displayed to the user in response to an access request.

RADIUS_CALLBACK_NUMBER(int)

The Callback-Number attribute. The attribute value is astringcontaining the dialing string to use for callback.

RADIUS_CALLBACK_ID(int)

The Callback-Id attribute. The attribute value is astringcontaining an implementation-specific name of the place to be called.

RADIUS_FRAMED_ROUTE(int)

The Framed-Route attribute. The attribute value is astringcontaining an implementation-specific set of routes to be configured for the user.

RADIUS_FRAMED_IPX_NETWORK(int)

The Framed-IPX-Network attribute. The attribute value is anintcontaining the IPX network to be configured for the user, or0xFFFFFFFEto indicate that the RADIUS client should select the network, and can be accessed viaradius_cvt_int().

RADIUS_STATE(int)

The State attribute. The attribute value is an implementation-definedstringincluded in an Access-Challenge from a server that must be included in the subsequent Access-Request, and can be set usingradius_put_attr().

RADIUS_CLASS(int)

The Class attribute. The attribute value is an arbitrarystringincluded in an Access-Accept message that should then be sent to the accounting server in Accounting-Request messages, and can be set usingradius_put_attr().

RADIUS_VENDOR_SPECIFIC(int)

The Vendor-Specific attribute. In general, vendor attribute values should be set usingradius_put_vendor_addr(),radius_put_vendor_attr(),radius_put_vendor_int()andradius_put_vendor_string(), rather than directly.

This constant is mostly useful when interpreting vendor specific attributes in responses from a RADIUS server; when a vendor specific attribute is received, theradius_get_vendor_attr()function should be used to access the vendor ID, attribute type and attribute value.

RADIUS_SESSION_TIMEOUT(int)

Session timeout

RADIUS_IDLE_TIMEOUT(int)

Idle timeout

RADIUS_TERMINATION_ACTION(int)

Termination action

RADIUS_CALLED_STATION_ID(int)

Called Station Id

RADIUS_CALLING_STATION_ID(int)

Calling Station Id

RADIUS_NAS_IDENTIFIER(int)

NAS ID

RADIUS_PROXY_STATE(int)

Proxy State

RADIUS_LOGIN_LAT_SERVICE(int)

Login LAT Service

RADIUS_LOGIN_LAT_NODE(int)

Login LAT Node

RADIUS_LOGIN_LAT_GROUP(int)

Login LAT Group

Framed Appletalk Link

RADIUS_FRAMED_APPLETALK_NETWORK(int)

Framed Appletalk Network

RADIUS_FRAMED_APPLETALK_ZONE(int)

Framed Appletalk Zone

RADIUS_CHAP_CHALLENGE(int)

Challenge

RADIUS_NAS_PORT_TYPE(int)

NAS port type, one of:

  • RADIUS_ASYNC
  • RADIUS_SYNC
  • RADIUS_ISDN_SYNC
  • RADIUS_ISDN_ASYNC_V120
  • RADIUS_ISDN_ASYNC_V110
  • RADIUS_VIRTUAL
  • RADIUS_PIAFS
  • RADIUS_HDLC_CLEAR_CHANNEL
  • RADIUS_X_25
  • RADIUS_X_75
  • RADIUS_G_3_FAX
  • RADIUS_SDSL
  • RADIUS_ADSL_CAP
  • RADIUS_ADSL_DMT
  • RADIUS_IDSL
  • RADIUS_ETHERNET
  • RADIUS_XDSL
  • RADIUS_CABLE
  • RADIUS_WIRELESS_OTHER
  • RADIUS_WIRELESS_IEEE_802_11

RADIUS_PORT_LIMIT(int)

Port Limit

RADIUS_LOGIN_LAT_PORT(int)

Login LAT Port

RADIUS_CONNECT_INFO(int)

Connect info

RADIUS_ACCT_STATUS_TYPE(int)

Accounting status type, one of:

  • RADIUS_START
  • RADIUS_STOP
  • RADIUS_ACCOUNTING_ON
  • RADIUS_ACCOUNTING_OFF

RADIUS_ACCT_DELAY_TIME(int)

Accounting delay time

RADIUS_ACCT_INPUT_OCTETS(int)

Accounting input bytes

RADIUS_ACCT_OUTPUT_OCTETS(int)

Accounting output bytes

RADIUS_ACCT_SESSION_ID(int)

Accounting session ID

RADIUS_ACCT_AUTHENTIC(int)

Accounting authentic, one of:

  • RADIUS_AUTH_RADIUS
  • RADIUS_AUTH_LOCAL
  • RADIUS_AUTH_REMOTE

RADIUS_ACCT_SESSION_TIME(int)

Accounting session time

RADIUS_ACCT_INPUT_PACKETS(int)

Accounting input packets

RADIUS_ACCT_OUTPUT_PACKETS(int)

Accounting output packets

RADIUS_ACCT_TERMINATE_CAUSE(int)

Accounting terminate cause, one of:

  • RADIUS_TERM_USER_REQUEST
  • RADIUS_TERM_LOST_CARRIER
  • RADIUS_TERM_LOST_SERVICE
  • RADIUS_TERM_IDLE_TIMEOUT
  • RADIUS_TERM_SESSION_TIMEOUT
  • RADIUS_TERM_ADMIN_RESET
  • RADIUS_TERM_ADMIN_REBOOT
  • RADIUS_TERM_PORT_ERROR
  • RADIUS_TERM_NAS_ERROR
  • RADIUS_TERM_NAS_REQUEST
  • RADIUS_TERM_NAS_REBOOT
  • RADIUS_TERM_PORT_UNNEEDED
  • RADIUS_TERM_PORT_PREEMPTED
  • RADIUS_TERM_PORT_SUSPENDED
  • RADIUS_TERM_SERVICE_UNAVAILABLE
  • RADIUS_TERM_CALLBACK
  • RADIUS_TERM_USER_ERROR
  • RADIUS_TERM_HOST_REQUEST

RADIUS_ACCT_MULTI_SESSION_ID(int)

Accounting multi session ID

Accounting link count



RADIUS Vendor Specific Attribute Types

RADIUS_VENDOR_MICROSOFT(int)

Microsoft specific vendor attributes (» RFC 2548), one of:

  • RADIUS_MICROSOFT_MS_CHAP_RESPONSE
  • RADIUS_MICROSOFT_MS_CHAP_ERROR
  • RADIUS_MICROSOFT_MS_CHAP_PW_1
  • RADIUS_MICROSOFT_MS_CHAP_PW_2
  • RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW
  • RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW
  • RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
  • RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
  • RADIUS_MICROSOFT_MS_RAS_VENDOR
  • RADIUS_MICROSOFT_MS_CHAP_DOMAIN
  • RADIUS_MICROSOFT_MS_CHAP_CHALLENGE
  • RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS
  • RADIUS_MICROSOFT_MS_BAP_USAGE
  • RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD
  • RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT
  • RADIUS_MICROSOFT_MS_MPPE_SEND_KEY
  • RADIUS_MICROSOFT_MS_MPPE_RECV_KEY
  • RADIUS_MICROSOFT_MS_RAS_VERSION
  • RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD
  • RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD
  • RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON
  • RADIUS_MICROSOFT_MS_FILTER
  • RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE
  • RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE
  • RADIUS_MICROSOFT_MS_CHAP2_RESPONSE
  • RADIUS_MICROSOFT_MS_CHAP2_SUCCESS
  • RADIUS_MICROSOFT_MS_CHAP2_PW
  • RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER
  • RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER
  • RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER
  • RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER
  • RADIUS_MICROSOFT_MS_ARAP_CHALLENGE




Ejemplos

¿Cómo iniciar?

  • Obtener un recurso radius
  • Configurar la librería
  • Crear la petición
  • Poner atributos
  • Enviar la petición
  • Recibir atributos
  • Cerrar el recurso radius (opcional)
También sirve echar un vistazo a los ejemplos en este paquete.

El paquete contiene un ejemplo de script php. Este script demuestra como autenticar con radius utilizando PAP o CHAP (md5). Si se autentica con servidores Microsoft Radius entonces no le será posible utilizar CHAP (md5). Si quisiera autenticarse con servidores Microsoft tiene que utilizar MS-CHAPv1 o MS-CHAPv2, pero es más complicado, porque usted necesita md4, sha1 y des para generar los datos correctos. Los ejemplos adjuntos demuestran todos los métodos de autenticación, incluyendo MS-CHAPv1 y MS-CHAPv2. Para tener funcionando MS-CHAP necesita las extensionesmcryptymhashiniciando con la version 1.2 de este paquete, la extensión mcrypt ya no es necesaria.



Funciones Radius


radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_openCrea un manejador Radius para el conteo

Descripción

radius_acct_open():resource

Valores devueltos

Devuelve un manejador en caso de tener éxito,falseen caso de error. Esta función falla solamente si hay insuficiencia de memoria.

Ejemplos

Ejemplo #1radius_acct_open()example

<?php
$res
=radius_acct_open()
or die (
"No se pudo crear un manejador handle");
print(
"Manejador creado exitosamente");
?>



radius_add_server

(PECL radius >= 1.1.0)

radius_add_serverAdds a server

Descripción

radius_add_server(
    resource$radius_handle,
    string$hostname,
    int$port,
    string$secret,
    int$timeout,
    int$max_tries
):bool

radius_add_server()may be called multiple times, and it may be used together withradius_config(). At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin fashion until a valid response is received, or until each server'smax_trieslimit has been reached.

Parámetros

radius_handle

hostname

Thehostnameparameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form.

port

Theportspecifies the UDP port to contact on the server. If port is given as 0, the library looks up theradius/udporradacct/udpservice in the network services database, and uses the port found there. If no entry is found, the library uses the standard Radius ports, 1812 for authentication and 1813 for accounting.

secret

The shared secret for the server host is passed to thesecretparameter. The Radius protocol ignores all but the leading 128 bytes of the shared secret.

timeout

The timeout for receiving replies from the server is passed to thetimeoutparameter, in units of seconds.

max_tries

The maximum number of repeated requests to make before giving up is passed into themax_tries.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1radius_add_server()example

<?php
if (!radius_add_server($res,'radius.example.com',1812,'testing123',3,3)) {
echo
'RadiusError:'.radius_strerror($res)."\n<br>";
exit;
}
?>

Ver también



radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_openCrea un identificador de Radius para la autenticación

Descripción

radius_auth_open():resource

Valores devueltos

Devuelve un manejador en caso de éxito,falseen caso de error. Esta función sólo falla si hay insuficiente memoria disponible.

Ejemplos

Ejemplo #1 Ejemplo deradius_auth_open()

<?php
$radh
=radius_auth_open()
or die (
"No se pudo crear el manejador");
echo
"Manejador creado con éxito";
?>



radius_close

(PECL radius >= 1.1.0)

radius_closeLibera todos los recursos

Descripción

radius_close(resource$radius_handle):bool

No es necesario llamar a esta función debido a que php libera todos los recursos al final de cada petición.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



radius_config

(PECL radius >= 1.1.0)

radius_configCauses the library to read the given configuration file

Descripción

radius_config(resource$radius_handle,string$file):bool

Before issuing any Radius requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to callradius_config().radius_config()causes the library to read a configuration file whose format is described in» radius.conf.

Parámetros

radius_handle

file

The pathname of the configuration file is passed as the file argument toradius_config(). The library can also be configured programmatically by calls toradius_add_server().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



radius_create_request

(PECL radius >= 1.1.0)

radius_create_requestCreate accounting or authentication request

Descripción

radius_create_request(resource$radius_handle,int$type):bool

A Radius request consists of a code specifying the kind of request, and zero or more attributes which provide additional information. To begin constructing a new request, callradius_create_request().

Nota:Attention: You must call this function, before you can put any attribute!

Parámetros

radius_handle

type

Type isRADIUS_ACCESS_REQUESTorRADIUS_ACCOUNTING_REQUEST.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1radius_create_request()example

<?php
if (!radius_create_request($res,RADIUS_ACCESS_REQUEST)) {
echo
'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>

Ver también



radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addrConverts raw data to IP-Address

Descripción

radius_cvt_addr(string$data):string

Converts raw data to IP-Address

Parámetros

data

Input data

Valores devueltos

Returns the IP-Address.

Ejemplos

Ejemplo #1radius_cvt_addr()example

<?php
while ($resa=radius_get_attr($res)) {

if (!
is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}

$attr=$resa['attr'];
$data=$resa['data'];

switch (
$attr) {

case
RADIUS_FRAMED_IP_ADDRESS:
$ip=radius_cvt_addr($data);
echo
"IP:$ip<br>\n";
break;

case
RADIUS_FRAMED_IP_NETMASK:
$mask=radius_cvt_addr($data);
echo
"MASK:$mask<br>\n";
break;
}
}
?>

Ver también



radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_intConverts raw data to integer

Descripción

radius_cvt_int(string$data):int

Converts raw data to integer

Parámetros

data

Input data

Valores devueltos

Returns the integer, retrieved from data.

Ejemplos

Ejemplo #1radius_cvt_int()example

<?php
while ($resa=radius_get_attr($res)) {

if (!
is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}

$attr=$resa['attr'];
$data=$resa['data'];

switch (
$attr) {

case
RADIUS_FRAMED_MTU:
$mtu=radius_cvt_int($data);
echo
"MTU:$mtu<br>\n";
break;
}
}
?>

Ver también



radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_stringConverts raw data to string

Descripción

radius_cvt_string(string$data):string

Converts raw data to string

Parámetros

data

Input data

Valores devueltos

Returns the string, retrieved from data.

Ejemplos

Ejemplo #1radius_cvt_string()example

<?php
while ($resa=radius_get_attr($res)) {

if (!
is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}

$attr=$resa['attr'];
$data=$resa['data'];

switch (
$attr) {

case
RADIUS_FILTER_ID:
$id=radius_cvt_string($data);
echo
"Filter ID:$id<br>\n";
break;
}
}
?>

Ver también



radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_keyDerives mppe-keys from mangled data

Descripción

radius_demangle_mppe_key(resource$radius_handle,string$mangled):string

When using MPPE with MS-CHAPv2, the send- and recv-keys are mangled (see» RFC 2548), however this function is useless, because I don't think that there is or will be a PPTP-MPPE implementation in PHP.

Parámetros

radius_handle

El recurso RADIUS.

mangled

The mangled data to demangle

Valores devueltos

Returns the demangled string, orfalseon error.



radius_demangle

(PECL radius >= 1.2.0)

radius_demangleDemangles data

Descripción

radius_demangle(resource$radius_handle,string$mangled):string

Some data (Passwords, MS-CHAPv1 MPPE-Keys) is mangled for security reasons, and must be demangled before you can use them.

Parámetros

radius_handle

El recurso RADIUS.

mangled

The mangled data to demangle

Valores devueltos

Returns the demangled string, orfalseon error.



radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attrExtracts an attribute

Descripción

radius_get_attr(resource$radius_handle):mixed

Like Radius requests, each response may contain zero or more attributes. After a response has been received successfully byradius_send_request(), its attributes can be extracted one by one usingradius_get_attr(). Each timeradius_get_attr()is called, it gets the next attribute from the current response.

Parámetros

radius_handle

El recurso RADIUS.

Valores devueltos

Returns an associative array containing the attribute-type and the data, or error number <= 0.

Ejemplos

Ejemplo #1radius_get_attr()example

<?php
while ($resa=radius_get_attr($res)) {

if (!
is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}

$attr=$resa['attr'];
$data=$resa['data'];
printf("Got Attr:%d %d Bytes %s\n",$attr,strlen($data),bin2hex($data));
}
?>

Ver también



radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_dataExtracts the data from a tagged attribute

Descripción

radius_get_tagged_attr_data(string$data):string|false

If a tagged attribute has been returned fromradius_get_attr(),radius_get_tagged_attr_data()will return the data from the attribute.

Parámetros

data

The tagged attribute to be decoded.

Valores devueltos

Returns the data from the tagged attribute ofalseen caso de error.

Ejemplos

Ejemplo #1radius_get_tagged_attr_data()example

<?php
while ($resa=radius_get_attr($res)) {
if (!
is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}

$attr=$resa['attr'];
$data=$resa['data'];

$tag=radius_get_tagged_attr_tag($data);
$value=radius_get_tagged_attr_data($data);

printf("Got tagged attribute with tag %d and value %s\n",$tag,$value);
}
?>

Ver también



radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tagExtracts the tag from a tagged attribute

Descripción

radius_get_tagged_attr_tag(string$data):int|false

If a tagged attribute has been returned fromradius_get_attr(),radius_get_tagged_attr_data()will return the tag from the attribute.

Parámetros

data

The tagged attribute to be decoded.

Valores devueltos

Returns the tag from the tagged attribute ofalseen caso de error.

Ejemplos

Ejemplo #1radius_get_tagged_attr_tag()example

<?php
while ($resa=radius_get_attr($res)) {
if (!
is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}

$attr=$resa['attr'];
$data=$resa['data'];

$tag=radius_get_tagged_attr_tag($data);
$value=radius_get_tagged_attr_data($data);

printf("Got tagged attribute with tag %d and value %s\n",$tag,$value);
}
?>

Ver también



radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attrExtracts a vendor specific attribute

Descripción

radius_get_vendor_attr(string$data):array

Ifradius_get_attr()returnsRADIUS_VENDOR_SPECIFIC,radius_get_vendor_attr()may be called to determine the vendor.

Parámetros

data

Input data

Valores devueltos

Returns an associative array containing the attribute-type, vendor and the data, orfalseon error.

Ejemplos

Ejemplo #1radius_get_vendor_attr()example

<?php
while ($resa=radius_get_attr($res)) {

if (!
is_array($resa)) {
printf("Error getting attribute: %s\n",radius_strerror($res));
exit;
}

$attr=$resa['attr'];
$data=$resa['data'];
printf("Got Attr:%d %d Bytes %s\n",$attr,strlen($data),bin2hex($data));
if (
$attr==RADIUS_VENDOR_SPECIFIC) {

$resv=radius_get_vendor_attr($data);
if (
is_array($resv)) {
$vendor=$resv['vendor'];
$attrv=$resv['attr'];
$datav=$resv['data'];
printf("Got Vendor Attr:%d %d Bytes %s\n",$attrv,strlen($datav),bin2hex($datav));
}

}
}
?>

Ver también



radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addrAttaches an IP address attribute

Descripción

radius_put_addr(
    resource$radius_handle,
    int$type,
    string$addr,
    int$options= 0,
    int$tag= ?
):bool

Attaches an IP address attribute to the current RADIUS request.

Nota:

Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.

Parámetros

radius_handle

El recurso RADIUS.

type

El tipo de atributo.

addr

An IPv4 address in string form, such as10.0.0.1.

options

Una máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.

tag

LA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
PECL radius 1.3.0Theoptionsandtagparameters were added.



radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attrAttaches a binary attribute

Descripción

radius_put_attr(
    resource$radius_handle,
    int$type,
    string$value,
    int$options= 0,
    int$tag= ?
):bool

Attaches a binary attribute to the current RADIUS request.

Nota:

Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.

Parámetros

radius_handle

El recurso RADIUS.

type

El tipo de atributo.

value

The attribute value, which will be treated as a raw binary string.

options

Una máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.

tag

LA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
PECL radius 1.3.0Theoptionsandtagparameters were added.

Ejemplos

Ejemplo #1radius_put_attr()example

<?php
mt_srand
(time());
$chall=mt_rand();
$chapval=md5(pack('Ca*',1,'sepp'.$chall));
$pass=pack('CH*',1,$chapval);
if (!
radius_put_attr($res,RADIUS_CHAP_PASSWORD,$pass)) {
echo
'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>

Ver también



radius_put_int

(PECL radius >= 1.1.0)

radius_put_intAttaches an integer attribute

Descripción

radius_put_int(
    resource$radius_handle,
    int$type,
    int$value,
    int$options= 0,
    int$tag= ?
):bool

Attaches an integer attribute to the current RADIUS request.

Nota:

Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.

Parámetros

radius_handle

El recurso RADIUS.

type

El tipo de atributo.

value

The attribute value.

options

Una máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.

tag

LA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
PECL radius 1.3.0Theoptionsandtagparameters were added.

Ejemplos

Ejemplo #1radius_put_int()example

<?php
if (!radius_put_int($res,RAD_FRAMED_PROTOCOL,RAD_PPP)) {
echo
'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>

Ver también



radius_put_string

(PECL radius >= 1.1.0)

radius_put_stringAttaches a string attribute

Descripción

radius_put_string(
    resource$radius_handle,
    int$type,
    string$value,
    int$options= 0,
    int$tag= ?
):bool

Attaches a string attribute to the current RADIUS request. In general,radius_put_attr()is a more useful function for attaching string attributes, as it is binary safe.

Nota:

Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.

Parámetros

radius_handle

El recurso RADIUS.

type

El tipo de atributo.

value

The attribute value. This value is expected by the underlying library to be null terminated, therefore this parameter is not binary safe.

options

Una máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.

tag

LA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
PECL radius 1.3.0Theoptionsandtagparameters were added.

Ejemplos

Ejemplo #1radius_put_string()example

<?php
if (!radius_put_string($res,RADIUS_USER_NAME,'billy')) {
echo
'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>

Ver también



radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addrAttaches a vendor specific IP address attribute

Descripción

radius_put_vendor_addr(
    resource$radius_handle,
    int$vendor,
    int$type,
    string$addr
):bool

Attaches an IP address vendor specific attribute to the current RADIUS request.

Nota:

Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.

Parámetros

radius_handle

El recurso RADIUS.

vendor

El ID del vendedor.

type

El tipo de atributo.

addr

An IPv4 address in string form, such as10.0.0.1.

options

Una máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.

tag

LA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
PECL radius 1.3.0Theoptionsandtagparameters were added.



radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attrAttaches a vendor specific binary attribute

Descripción

radius_put_vendor_attr(
    resource$radius_handle,
    int$vendor,
    int$type,
    string$value,
    int$options= 0,
    int$tag= ?
):bool

Attaches a vendor specific binary attribute to the current RADIUS request.

Nota:

Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.

Parámetros

radius_handle

El recurso RADIUS.

vendor

El ID del vendedor.

type

El tipo de atributo.

value

The attribute value, which will be treated as a raw binary string.

options

Una máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.

tag

LA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
PECL radius 1.3.0Theoptionsandtagparameters were added.

Ejemplos

Ejemplo #1radius_put_vendor_attr()example

<?php
if (!radius_put_vendor_attr($res,RADIUS_VENDOR_MICROSOFT,RAD_MICROSOFT_MS_CHAP_CHALLENGE,$challenge)) {
echo
'RadiusError:'.radius_strerror($res)."\n<br />";
exit;
}
?>

Ver también



radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_intAttaches a vendor specific integer attribute

Descripción

radius_put_vendor_int(
    resource$radius_handle,
    int$vendor,
    int$type,
    int$value,
    int$options= 0,
    int$tag= ?
):bool

Attaches a vendor specific integer attribute to the current RADIUS request.

Nota:

Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.

Parámetros

radius_handle

El recurso RADIUS.

vendor

El ID del vendedor.

type

El tipo de atributo.

value

The attribute value.

options

Una máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.

tag

LA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
PECL radius 1.3.0Theoptionsandtagparameters were added.

Ver también



radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_stringAttaches a vendor specific string attribute

Descripción

radius_put_vendor_string(
    resource$radius_handle,
    int$vendor,
    int$type,
    string$value,
    int$options= 0,
    int$tag= ?
):bool

Attaches a vendor specific string attribute to the current RADIUS request. In general,radius_put_vendor_attr()is a more useful function for attaching string attributes, as it is binary safe.

Nota:

Se debe crear una solicitud medianteradius_create_request()antes de llamar a esta función.

Parámetros

radius_handle

El recurso RADIUS.

vendor

El ID del vendedor.

type

El tipo de atributo.

value

The attribute value. This value is expected by the underlying library to be null terminated, therefore this parameter is not binary safe.

options

Una máscara de bits de las opciones de atributo. Las opciones disponibles incluyenRADIUS_OPTION_TAGGEDyRADIUS_OPTION_SALT.

tag

LA etiqueta de atributo. Este parámetro es ignorado a menos que la opciónRADIUS_OPTION_TAGGEDesté establecida.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
PECL radius 1.3.0Theoptionsandtagparameters were added.

Ver también



radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticatorReturns the request authenticator

Descripción

radius_request_authenticator(resource$radius_handle):string

The request authenticator is needed for demangling mangled data like passwords and encryption-keys.

Parámetros

radius_handle

El recurso RADIUS.

Valores devueltos

Returns the request authenticator as string, orfalseon error.

Ver también



radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attrSalt-encrypts a value

Descripción

radius_salt_encrypt_attr(resource$radius_handle,string$data):string|false

Applies the RADIUS salt-encryption algorithm to the given value.

In general, this is achieved automatically by providing theRADIUS_OPTION_SALToption to an attribute setter function, but this function can be used if low-level request construction is required.

Parámetros

data

The data to be salt-encrypted.

Valores devueltos

Returns the salt-encrypted data ofalseen caso de error.

Ver también



radius_send_request

(PECL radius >= 1.1.0)

radius_send_requestSends the request and waits for a reply

Descripción

radius_send_request(resource$radius_handle):int

After the Radius request has been constructed, it is sent byradius_send_request().

Theradius_send_request()function sends the request and waits for a valid reply, retrying the defined servers in round-robin fashion as necessary.

Parámetros

radius_handle

El recurso RADIUS.

Valores devueltos

If a valid response is received,radius_send_request()returns the Radius code which specifies the type of the response. This will typically beRADIUS_ACCESS_ACCEPT,RADIUS_ACCESS_REJECT, orRADIUS_ACCESS_CHALLENGE. If no valid response is received,radius_send_request()returnsfalse.

Ver también



radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secretReturns the shared secret

Descripción

radius_server_secret(resource$radius_handle):string

The shared secret is needed as salt for demangling mangled data like passwords and encryption-keys.

Parámetros

radius_handle

El recurso RADIUS.

Valores devueltos

Returns the server's shared secret as string, orfalseon error.



radius_strerror

(PECL radius >= 1.1.0)

radius_strerrorDevuelve un mensaje de error

Descripción

radius_strerror(resource$radius_handle):string

Si las funciones radio fallan entonces guardan un mensaje de error. Este mensaje de error puede ser obtenido con esta función.

Valores devueltos

Devuelve mensajes de error como string de funciones radio fallidas.


Tabla de contenidos





Extensiones específicas de la línea de comandos


GNU Readline


Introducción

Las funciones de readline implementan una interfaz a la biblioteca GNU Readline. Estas funciones proporcionan líneas de comando editables. Un ejemplo es Bash, que permite utilizar las teclas de dirección para insertar caracteres o desplazarse a través del historial de comandos. Debido a la naturaleza interactiva de esta biblioteca, será de poca utilidad para la creación de aplicaciones Web, pero puede ser útil cuando se escriben scripts utilizando lalínea de comandos.

A partir de PHP 7.1.0 esta extensión está soportada en Windows.

Precaución

¡La extensión de la línea de lectura no es segura para el hilo! Por lo tanto, se desaconseja su uso con cualquier SAPI verdaderamente segura para los hilos (como el Apache mod_winnt).



Instalación/Configuración

Tabla de contenidos


Requerimientos

Para usar las funciones readline, es necesario instalar libreadline. Se puede encontrar libreadline en la página principal del proyecto GNU Readline, en» http://cnswww.cns.cwru.edu/~chet/readline/rltop.html. Este proyecto es administrado por Chet Ramey, quien es también el autor de Bash.

También puede utilizar estas funciones con la libreria libedit, un reemplazo no-GPL para la biblioteca readline. La biblioteca libedit tiene licencia BSD y está disponible para su descarga desde» http://www.thrysoee.dk/editline/.



Instalación

Para utilizar estas funciones, debe compilar la versión CGI o CLI de PHP con soporte para readline. Es necesario configurar PHP--with-readline[=DIR]. Si desea utilizar el reemplazo de readline libedit, es necesario configurar PHP--with-libedit[=DIR].

En Windows esta extensión está disponible por defecto a partir de PHP 7.1.0.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Opciones de configuración Readline
NombrePor defectoCambiableHistorial de cambios
cli.pager""PHP_INI_ALL 
cli.prompt"\\b \\> "PHP_INI_ALL 

He aquí una breve explicación de las directivas de configuración.

cli.pagerstring

Herramienta externa para mostrar la salida de lalínea de comandos.

cli.promptstring

VéaseLínea de Comandos.



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

READLINE_LIB(string)
La biblioteca que se utiliza para el soporte de la línea de lectura; actualmentereadlineolibedit. Disponible a partir de PHP 5.5.0.


Funciones Readline


readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_historyAgrega una línea a la historia

Descripción

readline_add_history(string$line):bool

Esta función agrega una línea a la historia de la línea de comandos.

Parámetros

line

La línea a ser agregada en la historia.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_installInicializa la interfaz de llamada de readline y la terminal, imprime el mensaje y retorna inmediatamente

Descripción

readline_callback_handler_install(string$prompt,callable$callback):bool

Configura una interfaz de llamada readline y luego imprimemensaje, luego de lo cual retorna. Si llamas a esta función más de una vez sin eliminar la interfaz de llamada anterior automaticamente reemplazará la versión anterior.

La interfaz de llamada es útil cuando se combina constream_select()ya que permite la intercalación de IO (entrada/salida) y entrada del usuario, a diferencia dereadline().

Parámetros

mensaje

El mensaje a imprimir.

funcion

La funciónfuncionrecibe un parámetro; la entrada del usuario retornada.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo de interfaz de llamada readline

<?php
functionrl_callback($ret)
{
global
$c,$prompting;

echo
"Has ingresado:$ret\n";
$c++;

if (
$c>10) {
$prompting=false;
readline_callback_handler_remove();
} else {
readline_callback_handler_install("[$c] Ingresa algo: ",'rl_callback');
}
}

$c=1;
$prompting=true;

readline_callback_handler_install("[$c] Ingresa algo: ",'rl_callback');

while (
$prompting) {
$w=NULL;
$e=NULL;
$n=stream_select($r= array(STDIN),$w,$e,null);
if (
$n&&in_array(STDIN,$r)) {
// lee un carácter, llama a la funcion cuando una nueva línea es ingresada
readline_callback_read_char();
}
}

echo
"Mensaje deshabilitado. Todo hecho.\n";
?>

Ver también

  • readline_callback_handler_remove()- Elimina una interfaz de llamada anteriormente agregada y retaura la configuración de terminal
  • readline_callback_read_char()- Lee un carácter e informa a la interfaz de llamada de readline cuando una línea es recibida
  • stream_select()- Ejecuta el equivalente de la llamada al sistema select() sobre las matrices de flujos dadas con un tiempo de espera especificado por tv_sec y tv_usec



readline_callback_handler_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_removeElimina una interfaz de llamada anteriormente agregada y retaura la configuración de terminal

Descripción

readline_callback_handler_remove():bool

Elimina una interfaz de llamada configurada anteriormente y restaura la configuración de terminal.

Valores devueltos

Retornatruesi una interfaz de llamada instalada anteriormente fue eliminada, ofalsesi no pudo hallarse una.

Ejemplos

Verreadline_callback_handler_install()para un ejemplo sobre como utilizar la interfaz de llamada de readline.

Ver también



readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_charLee un carácter e informa a la interfaz de llamada de readline cuando una línea es recibida

Descripción

readline_callback_read_char():void

Lee un carácter del usuario. Cuando una línea es recibida, esta función informa a la interfaz de llamada de readline utilizandoreadline_callback_handler_install(), especificando así que hay una línea lista como entrada.

Valores devueltos

No devuelve ningún valor.

Ejemplos

Veásereadline_callback_handler_install()para un ejemplo sobre cómo utilizar la interfaz de llamada de readline.

Ver también



readline_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_historyLimpia el historial

Descripción

readline_clear_history():bool

Esta función limpia completamente el historial de línea de comandos.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_functionRegistra una función de autocompletado

Descripción

readline_completion_function(callable$function):bool

Esta función reistra una función para ser utilizada para autocompletar comandos. Es la misma funcionalidad que obtendrías si presionas la tecla Tab mientras escribes un comando en Bash.

Parámetros

funcion

El nombre de una función que acepta una línea de comandos parcial y devuelve un array con las entradas coincidentes.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_infoObtiene/Modifica variables internas a readline

Descripción

readline_info(string$varname= ?,string$newvalue= ?):mixed

Obtiene o modifica numerosas variables internas de readline.

Parámetros

variable

Un nombre de variable.

valor

Si se especifica, este será el nuevo valor de la variable.

Valores devueltos

Si esta función es llamada sin parámetros, retornará un array de valores para todos los usos de readline. Los elementos estarán indexados por los siguientes valores: done, end, erase_empty_line, library_version, line_buffer, mark, pending_input, point, prompt, readline_name, y terminal_name.

Si es llamado por uno o dos parámetros, el valor anterior de la variable es retornado.



readline_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_historyObtener el historial

Descripción

readline_list_history():array

Obtiene el historial completo de comandos.

Valores devueltos

Retorna un array correspondiente al historial completo de la línea de comandos. Los elementos son indexados por enteros, comenzando desde cero.



readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_lineInformar a readline que el cursor se ha movido a una nueva línea

Descripción

readline_on_new_line():void

Le informa a readline que el cursor se ha movido a una nueva línea.

Valores devueltos

No devuelve ningún valor.



readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_historyLee el historial

Descripción

readline_read_history(string$filename= ?):bool

Esta función lee el historial de comandos desde un archivo.

Parámetros

archivo

Ubicación del archivo que contiene el historial de comandos.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplayRedibuja la vista

Descripción

readline_redisplay():void

Redibuja readline para volver a dibujar la vista.

Valores devueltos

No devuelve ningún valor.



readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_historyEscribe el historial

Descripción

readline_write_history(string$filename= ?):bool

Esta función escribe el historial de comandos en un archivo.

Parámetros

archivo

Ubicación del archivo.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



readline

(PHP 4, PHP 5, PHP 7, PHP 8)

readlineLee una línea

Descripción

readline(string$prompt=null):string

Lee una sola línea del usuario. Debe agregar esta línea al historial utilizandoreadline_add_history().

Parámetros

mensaje

Puedes especificar un mensaje que se muestra al usuario.

Valores devueltos

Devuelve un único string del usuario. Esta línea retornada tiene el avance de línea al final eliminado.

Ejemplos

Ejemplo #1 Ejemplo dereadline()

<?php
//obtener 3 comandos del usuario
for ($i=0;$i<3;$i++) {
$linea=readline("Comando: ");
readline_add_history($linea);
}

//mostrar historial
print_r(readline_list_history());

//mostrar variables
print_r(readline_info());
?>


Tabla de contenidos





Extensiones de compresión y archivos


Bzip2


Introducción

Las funciones de bzip2 se utilizan para leer y escribir ficheros comprimidos con bzip2 (.bz2) de forma transparente.



Instalación/Configuración

Tabla de contenidos


Requerimientos

Este módulo usa las funciones de la librería» bzip2por Julian Seward. Este módulo requiere bzip2/libbzip2 version >= 1.0.x.



Instalación

El soporte deBzip2en PHP no está activado por defecto. Se necesita usar la opción de configuración--with-bz2[=DIR]al compilar PHP para activar soporte de bzip2.



Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración definidas enphp.ini.



Tipos de recursos

Esta extensión define un tipo de recurso: apunta a un archivo identificando el fichero bz2 a trabajar.




Constantes predefinidas

Esta extensión no tiene ninguna constante definida.



Ejemplos

Este ejemplo abre un fichero temporal y escribe una cadena de prueba en el, muestra el contenido del fichero.

Ejemplo #1 Pequeño ejemplo de bzip2

<?php

$filename
="/tmp/testfile.bz2";
$str="Esto es una cadena de prueba.\n";

// Abriendo fichero para escribir
$bz=bzopen($filename,"w");

// escribe la cadena en el fichero
bzwrite($bz,$str);

// cierra el fichero
bzclose($bz);

// abre el fichero para escritura
$bz=bzopen($filename,"r");

// lee 10 caracteres
echobzread($bz,10);

// muestra salida hasta el final del fichero (o los siguientes 1024 caracteres) y lo cierra.
echobzread($bz);

bzclose($bz);

?>


Funciones de Bzip2


bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcloseCierra un fichero bzip2

Descripción

bzclose(resource$bz):bool

Cierra el dado puntero del fichero bzip2.

Parámetros

bz

El puntero del fichero. Debe ser un puntero válido a un fichero abierto conbzopen()satisfactoriamente.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también

  • bzopen()- Abre un fichero comprimido con bzip2



bzcompress

(No version information available, might only be in Git)

bzcompressComprime una cadena en datos codificados en bzip2

Descripción

bzcompress(string$source,int$blocksize= 4,int$workfactor= 0):mixed

bzcompress()comprime la cadena dada y la devuelve como datos codificados con bzip2.

Parámetros

source

La cadena a comprimir.

blocksize

Especifica el blocksize usado durante la compresión y debería ser un número entre 1 y 9 siendo 9 la máxima compresión, pero también utiliza más recursos.

workfactor

Controla como se comportan las fases de compresión cuando se presenta en el peor de los casos, datos que se repiten continuamente. El valor puede estar entre 0 y 250 siendo 0 un caso especial.

Independientemente deworkfactor, el valor generado de salida es el mismo.

Valores devueltos

La cadena comprimida, o el número de error en caso de error.

Ejemplos

Ejemplo #1 Comprimiendo datos

<?php
$str
="sample data";
$bzstr=bzcompress($str,9);
echo
$bzstr;
?>

Ver también



bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompressDescomprime datos codificados con bzip2

Descripción

bzdecompress(string$source,int$small= 0):mixed

bzdecompress()descomprime el string pasado por parámetro que contiene los datos codificados en bzip2.

Parámetros

source

String a descomprimir.

small

Si estrue, se usará un algoritmo de descompresión alternativo que utiliza menos memoria (disminuye el requisito máximo de memoria a entorno a 2300K) pero por otra parte es la mitad de lento aproximadamente.

Consulte la» documentación de bzip2para más información sobre este comportamiento.

Valores devueltos

El string descromprimido, o el número de error en caso de error.

Ejemplos

Ejemplo #1 Descompresión de un String

<?php
$start_str
="This is not an honest face?";
$bzstr=bzcompress($start_str);

echo
"String Comprimido: ";
echo
$bzstr;
echo
"\n<br />\n";

$str=bzdecompress($bzstr);
echo
"String Descomprimido: ";
echo
$str;
echo
"\n<br />\n";
?>

Ver también

  • bzcompress()- Comprime una cadena en datos codificados en bzip2



bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrnoDevuelve el número de erro de bzip2

Descripción

bzerrno(resource$bz):int

Devuelve el número de error de cualquier error bzip2 devuelto por el puntero del fichero dado.

Parámetros

bz

El puntero del fichero. Debe ser un puntero a un fichero abierto conbzopen()satisfactoriamente.

Valores devueltos

Devuelve el número de error como entero.

Ver también

  • bzerror()- Devuelve el número de error y la cadena del error de bzip2 en un array
  • bzerrstr()- Devuelve una cadena de error de bzip2



bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrorDevuelve el número de error y la cadena del error de bzip2 en un array

Descripción

bzerror(resource$bz):array

Devuelve el número de error y la cadena de error de cualquier error bzip2 devuelto por el puntero del fichero dado.

Parámetros

bz

El puntero del fichero. Debe ser un puntero a un fichero abierto conbzopen()satisfactoriamente.

Valores devueltos

Devuelve un array asociativo, con el código de error en la entradaerrnoy el mensaje de error en la entradaerrstr.

Ejemplos

Ejemplo #1 Ejemplo debzerror()

<?php
$error
=bzerror($bz);

echo
$error["errno"];
echo
$error["errstr"];
?>

Ver también

  • bzerrno()- Devuelve el número de erro de bzip2
  • bzerrstr()- Devuelve una cadena de error de bzip2



bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstrDevuelve una cadena de error de bzip2

Descripción

bzerrstr(resource$bz):string

Obtiene la cadena de error de cualquier error bzip2 devuelto por el puntero dado.

Parámetros

bz

El puntero del fichero. Debe ser un puntero a un fichero abierto conbzopen()satisfactoriamente.

Valores devueltos

Devuelve una cadena que contiene el mensaje de error.

Ver también

  • bzerrno()- Devuelve el número de erro de bzip2
  • bzerror()- Devuelve el número de error y la cadena del error de bzip2 en un array



bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflushFuerza la escritura de todos los datos del búfer

Descripción

bzflush(resource$bz):bool

Fuerza la escritura de todos los datos del búfer bzip2 para el puntero del ficherobz.

Parámetros

bz

El puntero del fichero. Debe ser un puntero a un fichero abierto conbzopen()satisfactoriamente.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también

  • bzread()- Lectura segura de ficheros bzip2
  • bzwrite()- Escribe en un fichero bzip2 de forma segura binariamente



bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopenAbre un fichero comprimido con bzip2

Descripción

bzopen(string$filename,string$mode):resource

bzopen()abre un fichero bzip2 (.bz2) para lectura o escritura.

Parámetros

filename

El nombre del fichero a abrir, o un recurso de flujo existente.

mode

Similar a la funciónfopen(), solamente 'r' (lectura) y 'w' (escritura) están soportados. Todo lo demás hará que bzopen devuelvafalse.

Valores devueltos

Si al abrir el fichero se produce un error,bzopen()devolveráfalse, en caso contrario devolverá el puntero del nuevo fichero abierto.

Ejemplos

Ejemplo #1 Ejemplo debzopen()

<?php

$file
="/tmp/foo.bz2";
$bz=bzopen($file,"r") or die("No se pudo abrir el fichero$filepara lectura");

bzclose($bz);

?>

Ver también



bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzreadLectura segura de ficheros bzip2

Descripción

bzread(resource$bz,int$length= 1024):string

bzread()lee del puntero de fichero bzip2 pasado como parámetro.

La lectura finaliza una vez que se han leídolengthbytes (descomprimidos) o cuando se alcanza EOF, lo primero que suceda.

Parámetros

bz

El puntero al fichero. Tiene que ser válido y debe apuntar a un fichero que se haya abierto con éxito conbzopen().

length

Si no se especifica,bzread()leerá bloques de 1024 bytes (descomprimidos) al momento. Un máximo de 8192 bytes descomprimidos serán leídos.

Valores devueltos

Devuelve la información descomprimida, ofalseen caso de error.

Ejemplos

Ejemplo #1 ejemplo debzread()

<?php

$file
="/tmp/foo.bz2";
$bz=bzopen($file,"r") or die("No se ha podido abrir$file");

$decompressed_file='';
while (!
feof($bz)) {
$decompressed_file.=bzread($bz,4096);
}
bzclose($bz);

echo
"El contenido de$filees: <br />\n";
echo
$decompressed_file;

?>

Ver también

  • bzwrite()- Escribe en un fichero bzip2 de forma segura binariamente
  • feof()- Comprueba si el puntero a un archivo está al final del archivo
  • bzopen()- Abre un fichero comprimido con bzip2



bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwriteEscribe en un fichero bzip2 de forma segura binariamente

Descripción

bzwrite(resource$bz,string$data,int$length= ?):int

bzwrite()escribe una cadena en el fichero gzip2 dado.

Parámetros

bz

El puntero del fichero. Debe apuntar a un fichero abierto satisfactoriamente conbzopen().

data

Los datos a escribir.

length

Si se proporciona, la escritura terminará después de que ellength(no comprimido) en bytes hayan sido escritos o se haya llegado al final dedata, lo que llegue primero.

Valores devueltos

Devuelve el número de bytes escritos, ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo debzwrite()

<?php
$str
="uncompressed data";
$bz=bzopen("/tmp/foo.bz2","w");
bzwrite($bz,$str,strlen($str));
bzclose($bz);
?>

Ver también

  • bzread()- Lectura segura de ficheros bzip2
  • bzopen()- Abre un fichero comprimido con bzip2


Tabla de contenidos

  • bzclose— Cierra un fichero bzip2
  • bzcompress— Comprime una cadena en datos codificados en bzip2
  • bzdecompress— Descomprime datos codificados con bzip2
  • bzerrno— Devuelve el número de erro de bzip2
  • bzerror— Devuelve el número de error y la cadena del error de bzip2 en un array
  • bzerrstr— Devuelve una cadena de error de bzip2
  • bzflush— Fuerza la escritura de todos los datos del búfer
  • bzopen— Abre un fichero comprimido con bzip2
  • bzread— Lectura segura de ficheros bzip2
  • bzwrite— Escribe en un fichero bzip2 de forma segura binariamente



LZF


Introducción

LZF es un algoritmo de compresión muy rápido, ideal para ahorrar espacio con solamente un ligero costo de velocidad. Puede optimizarse para velocidad o espacio a la hora de compilar. Esta extensión utiliza la librería» liblzfpor Marc Lehmann para sus operaciones.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

Esta extensión» PECLno se distribuye con PHP. Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/lzf.

Pata utilizar estas funciones se debe compilar PHP con soporte para lzf empleando la opción de configuración--with-lzf[=DIR]. También se puede pasar--enable-lzf-better-compressionpara optimizar LZF para espacio en vez de para velocidad.

Los usuarios de Windows habilitaránphp_lzf.dlldentro dephp.inipara utilizar estas funciones. Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.



Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración definidas enphp.ini.



Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.




Constantes predefinidas

Esta extensión no tiene ninguna constante definida.



Funciones LZF


lzf_compress

(PECL lzf >= 0.1.0)

lzf_compressCompresión LZF

Descripción

lzf_compress(string$data):string

lzf_compress()comprime el stringdatadado utilizando codificación LZF.

Parámetros

data

El string a comprimir.

Valores devueltos

Devuelve los datos comprimidos ofalsesi ocurrió un error.

Ver también



lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompressDescompresión LZF

Descripción

lzf_decompress(string$data):string

lzf_compress()descomprime la cadenadatadada que contiene los datos codificados en lzf.

Parámetros

data

La cadena comprimida.

Valores devueltos

Devuelve los datos descomprimidos ofalsesi ocurrió un error.

Ver también



lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_forDetermina para qué fue optimizada la extensión LZF

Descripción

lzf_optimized_for():int

Determina para qué fue optimizada la extensión LZF durante la compilación.

Valores devueltos

Devuelve 1 si LZF fue optimizada para velocidad, 0 para compresión.


Tabla de contenidos




Phar


Introducción

La extensión phar proporciona una manera de colocar aplicaciones PHP enteras dentro de un único fichero llamado "phar" (PHP Archive) para una distribución e instalación sencillas. Además de proporcionar este servicio, la extensión phar también provee de un método de abstracción de formato de fichero para crear y manipular ficheros tar y zip a través de la clasePharData, tal como PDO proporciona una interfaz unificada para acceder a diferentes bases de datos. A diferencia de PDO, la cual no puede realizar conversiones entre bases de datos diferentes, Phar también realiza conversiones entre los formatos de ficheros tar, zip phar con una sencilla línea de código. VéasePhar::convertToExecutable()para un ejemplo.

¿Qué es phar? Lo archivos Phar están mejor caracterizados como una forma conveniente de agrupar varios ficheros en un único fichero. Como tal, un archvo phar proporciona una forma para distribuir una aplicación PHP completa en un único fichero y ejecutarla desde ese mismo fichero sin necesidad de extraerlo en el disco. Además, los archivos phar pueden ser ejecutados por PHP fácilmente al igual que cualquier otro fichero, tanto desde la línea de comandos como desde un servidor web. Phar a web server. Phar es como una memoria USB para aplicaciones PHP.

Phar implementa esta funcionalidad a través de unaEnvoltura de Flujo. Normalmente, para utilizar un fichero externo dentro de un script de PHP, se debería usarinclude

Ejemplo #1 Utilizar un fichero externo

<?php
include'/ruta/al/fichero/externo.php';
?>

Puede considerarse que PHP traduce realemte/ruta/al/fichero/externo.phpa una envoltura de flujo comofile:///ruta/al/fichero/externo.php, y bajo la cubierta de hecho hace uso de funciones de flujo de envolturas de flujo de ficheros para acceder a todos los ficheros locales.

Para utilizar un fichero llamadofichero.phpcontenido en un archivo phar/ruta/a/miphar.phar, la sintaxis es muy similar a la sintaxisfile://de arriba.

Ejemplo #2 Utilizar un fichero dentro de un archivo phar

<?php
include'phar:///ruta/a/miphar.phar/fichero.php';
?>

De hecho, se puede tratar un archivo phar exactamente como si fuera un disco externo, usando cualquiera de las funciones relacionadas confopen(),opendir()y funciones relacionadas conmkdir()para leer, cambiar, o crear nuevos ficheros y directorios dentro del archivo phar. Esto permite que aplicaciones de PHP completas sean distribuidas en un único fichero y ejecutarlas directamente desde ese fichero.

El uso más común de un archivo phar es distribuir una aplicación completa en un único fichero. Por ejemplo, el Instalador de PEAR que se incluye con las versiones de PHP está distribuido como un archivo phar. Para usar un archivo phar distribuido de esta forma, se puede ejecutar en línea de comandos o mediante un servidor web.

Los archivos phar pueden ser distribuidos como archivostar,zip, o como formato de ficheropharpersonalizado diseñado específicamente por la extensión phar. Cada formato de fichero tiene sus ventajas y desventajas. Los formatos de fichero tar y zip se pueden leer o extraer mediante cualquier herramienta de terceros que pueda leer el formato, pero necesia la extensión phar para ejecutarlo con PHP. El formato de fichero phar es personalizado y único para la extensión phar, y sólo puede ser creado por la extensión phar o el paquete de PEAR» PHP_Archive, pero tiene la ventaja de que las apliaciones creadas en este formato se ejecutarán incluso si la extensión phar no está habilitada.

En otras palabra, incluso con la extensión phar deshabilitada, se puede ejecutar o incluir un archivo basado en phar. El acceso a ficheros dentro de un archivo phar solamente es posible con la extesnión phar a menos que el archivo phar fuese creado por PHP_Archive.

La extensión phar también es capaz de convertir un archivo phar desde los formatos de fichero tar a zip o a phar en un único comando:

Ejemplo #3 Convertir un archivo phar, desde phar al formato de fichero tar

<?php
$phar
= newPhar('miphar.phar');
$pgz=$phar->convertToExecutable(Phar::TAR,Phar::GZ);// crea miphar.phar.tar.gz
?>

Phar puede comprimir ficheros individuales o un archivo entero usando la compresióngzipo labzip2, y puede verificar la integridad del archivo automáticamente a través del uso de las signaturas MD5, SHA-1, SHA-256 o SHA-512.

Por último, la extensión Phar se preocupa de la seguridad, y deshabilita el acceso a la escritura de archivos phar ejecutables de manera predeterminada, y requiere la deshabilitación a nivel de sistema del ajustephar.readonlyde php.ini para crear o modificar archivos phar. Los archivos tar y zip normales sin una rutina de interoperabilidad ejecutable siempre pueden ser creador o modificados utilizando la clasePharData.

Si está creando aplicaciones para su distribución, le interesará leerCómo crear Archivos Phar. Si desea más información de las diferencias entre los tres formatos de ficheros que soporta phar, debería leerPhar, Tar y Zip.

Si usa aplicaciones phar, existen consejos útiles enCómo utilizar archivos Phar

La palabraphares una composición dePHPyArchivey está basada indirectamente en el familiarjar(Java Archive) para los desarrolladores Java.

La implementación de archivos Phar está basada en el paquete de PEAR» PHP_Archive, y los detalles de implementación son similares, aunque la extensión Phar es mucho más potente. Además, la extensión Phar permite a la mayoría de las aplicaciones de PHP ejecutarse sin modificaciones, mientras que los archivos phar basados en PHP_Archive a menudo requieren una extensa modificiación para que funcionen.



Instalación/Configuración

Tabla de contenidos


Requerimientos

Phar requiere PHP 5.2.0 o superior. Las caracteristicas adicionales requieren la extensiónSPLpara aprovechar la iteración y el acceso a arrays del contenido de un fichero de Phar. El flujopharno requiere ninguna extensión adicional para que funcione.

Opcionalmente, se puede habilitar las extensioneszlibybzip2para aprovechar el soporte de phar comprimidos. Además, para aprovechar la firma OpenSSL, debe estar habilidata la extensiónOpenSSL.

Observe que un error en el filtro de flujoszlib.deflatecorregido en la versión 5.2.6 y posteriores de PHP puede ocasionar el truncamiento de archivos phar comprimidos con gzip bzip2.

PHP 5.3 configurado con--enable-zend-multibytehace quephardependa de la opción inidetect_unicode.



Instalación

La extensión Phar está integrada a partir de la versión 5.3.0 de PHP. Phar se puede instalar a través de la extensión PECL con las versiones anteriores de PHP. La» página de PECL de Pharcontiene información adicional y su historia.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

Opciones de Configuración de Flujos y Sistema de Ficheros
NombrePor defectoCambiableHistorial de cambios
phar.readonly"1"PHP_INI_ALL 
phar.require_hash"1"PHP_INI_ALL 
phar.cache_list""PHP_INI_SYSTEM 

He aquí una breve explicación de las directivas de configuración.

phar.readonlybool

Esta opción deshabilita la modificación o creación de archivos Phar usando el flujopharo el soporte para escritura de objetosPhar. Este ajuste debería estar siempre activado en máquinas de producción, ya que el soporte para escritura conveniente de la extensión phar podría permitir la simple creación de un virus basado en PHP al asociarse con otras vulnerabilidades de seguridad comunes.

Nota:

Este ajuste sólo puede ser desactivado en php.ini por motivos de seguridad. Siphar.readonlyestá deshabilitado en php.ini, un usuario puede habilitarphar.readonlyen un script o deshabilitarlo después. Siphar.readonlyestá habilitado en php.ini, un scrip puede "re-habilitar" inofensivamente la variable INI, pero no puede deshabilitarla.

phar.require_hashbool

Esta opción forzará a todos los archivos Phar abiertos a que contengan algún tipo de signatura (actualmente está soportadas MD5, SHA1, SHA256 y SHA512), y rehusará procesar cualquer archivo Phar que no contenga una signatura.

Nota:

Este ajuste sólo puede ser desactivado en php.ini por motivos de seguridad. Siphar.require_hashestá deshabilitado en php.ini, un usuario puede habilitarphar.require_hashen un script o deshabilitarlo después. Siphar.require_hashestá habilitado en php.ini, un scrip puede "re-habilitar" inofensivamente la variable INI, pero no puede deshabilitarla.

Este ajuste no afecta a la lectura de ficheros tar planos con la clasePharData.

Precaución

phar.require_hashno proporciona ninguna seguridad per se, es simplemente una medida contra la ejecución accidental de archivos Phar corruptos, porque cualquiera que pueda alterar el Phar podría corregir fácilmente la firma.

phar.cache_liststring

Permite mapear archivos phar para que sean preanalizados en el arranque del servidor web, proporcionando una mejora de rendimiento que saca ficheros en ejecución de un archivo phar casi tan rápido como si esos ficheros se ejecutaran desde una instalación tradicional basada en disco.

Ejemplo #1 Ejemplo de uso de phar.cache_list

en php.ini (windows):
phar.cache_list =C:\ruta\a\phar1.phar;C:\ruta\a\phar2.phar
en php.ini (unix):
phar.cache_list =/ruta/a/phar1.phar:/ruta/a/phar2.phar



Tipos de recursos

La extensión Phar proporciona el flujophar, el cual permite el acceso a ficheros contenidos en un phar de manera transparente. Véase también ladescripción de formato de fichero Phar.




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

Constantes de compresión de Phar
ConstanteValorDescripción
Phar::NONE(integer)0x00000000sin compresión
Phar::COMPRESSED(integer)0x0000F000máscara de bit que puede ser usada con banderas de fichero para determinar si está presente algún tipo de compresión
Phar::GZ(integer)0x00001000compression zlib (gzip)
Phar::BZ2(integer)0x00002000compression bzip2
Constanten de formato de fichero de Phar
ConstanteValorDescripción
Phar::SAME(integer)0conservar el mismo formato de fichero
Phar::PHAR(integer)1formato de fichero phar
Phar::TAR(integer)2formato de fichero tar
Phar::ZIP(integer)3formato de fichero zip
Constantes de signatura de Phar
ConstanteValorDescripción
Phar::MD5(integer)0x0001singnatura con el algoritmo hash md5
Phar::SHA1(integer)0x0002singnatura con el algoritmo hash sha1
Phar::SHA256(integer)0x0003singnatura con el algoritmo hash sha256 (requiere la extensión Hash)
Phar::SHA512(integer)0x0004singnatura con el algoritmo hash sha512 (requiere la extensión Hash)
Phar::OPENSSL(integer)0x0010signatura con la pareja de claves pública/privada de OpenSSL. Esta es una signatura de clave asimétrica verdadera.
Constantes de sobrescritura MIME de webPhar de Phar
ConstanteValorDescripción
Phar::PHP(integer)1usada para ordenar al parámetro de sobrescritura MIME dePhar::webPhar()que la extensión debería ser analizada como un fichero de PHP
Phar::PHPS(integer)2usada para ordenar al parámetro de sobrescritura MIME dePhar::webPhar()que la extensión debería ser analizada como un fichero fuente de PHP a través dehighlight_file()


Utilizar Archivos Phar

Tabla de contenidos


Utilizar Archivos Phar: Introduction

Los archivos phar son similares en concepto a los archivo JAR de Java, pero están adaptados a las necesidades y a la flexibilidad de aplicaciones de PHP. Un archivo Phar se usa para distribuir una aplicación o biblioteca PHP completa en un único fichero. Una aplicación de un archivo Phar se utiliza exactamente de la misma manera que otra aplicación PHP:

php aplicacion.phar
  

Utilizar una biblioteca de archivo Phar es idéntico a usar cualquier otra biblioteca de PHP:

<?php
include'biblioteca.phar';
?>

La envoltura de flujospharproporciona el núcleo de la extensión Phar, y está explicada en detalleaquí. La envoltura de flujos phar permite el acceso a los ficheros dentro de un archivo phar utilizando las funciones estándar de ficheros de PHPfopen(),opendir(), y y otras que trabajan sobre ficheros normales. La envoltura de flujospharsoporta todas las operaciones de lectura/escritura tanto en ficheros como en directorios.

<?php
include'phar://biblioteca.phar/fichero/interno.php';
header('Content-type: image/jpeg');
// a los phar se puede acceder con la ruta completa o mediante un alias
echofile_get_contents('phar:///ruta_completa/a/biblioteca.phar/imagenes/wow.jpg');
?>

La clasePharimplementa una funcionalidad avanzada para acceder a ficheros y crear arhivos phar. La clas Phar está explicada en detalleaquí.

<?php
try {
// abrir un phar existente
$p= newPhar('biblioteca.phar',0);
// Phar extiende la clase DirectoryIterator de SPL
foreach (newRecursiveIteratorIterator($p) as$fichero) {
// $fichero en una clase PharFileInfo, y hereda de SplFileInfo
echo$fichero->getFileName() ."\n";
echo
file_get_contents($fichero->getPathName()) ."\n";// mostrar el contenido;
}
if (isset(
$p['fichero/interno.php'])) {
var_dump($p['fichero/interno.php']->getMetadata());
}

// crear un nuevo phar - phar.readonly debe ser 0 en php.ini
// phar.readonly está habilitado por omisión por motivos de seguridad.
// En servidores de producción, los archivos Phar nunca se crean,
// sólo se ejecutan.
if (Phar::canWrite()) {
$p= newPhar('nuevo_phar.tar.phar',0,'nuevo_phar.tar.phar');
// hacerlo un archivo phar basado en tar, comprimido con gzip (.tar.gz)
$p=$p->convertToExecutable(Phar::TAR,Phar::GZ);

// crear una transacción - no se escribe nada en nuevo_phar.phar
// hasta que stopBuffering() sea llamado, aunque se necesita almacenamiento temporal
$p->startBuffering();
// añadir todos los ficheros de /ruta/del/proyecto, guardándolos en el phar con el prefijo "proyecto"
$p->buildFromIterator(newRecursiveIteratorIterator(newDirectoryIterator('/ruta/del/proyecto')),'/ruta/del/');

// añadir un nuevo fichero mediante la API de acceso a arrays
$p['fichero1.txt'] ='Información';
$fp=fopen('fichero_enorme.dat','rb');
// copiar toda la información del flujo
$p['datos/fichero_enorme.dat'] =$fp;

if (
Phar::canCompress(Phar::GZ)) {
$p['datos/fichero_enorme.dat']->compress(Phar::GZ);
}

$p['imagenes/wow.jpg'] =file_get_contents('imagenes/wow.jpg');
// cualquier valor se puede guardar como metainformación específica del fichero
$p['imagenes/wow.jpg']->setMetadata(array('mime-type'=>'image/jpeg'));
$p['index.php'] =file_get_contents('index.php');
$p->setMetadata(array('bootstrap'=>'index.php'));

// cuardar el archivo phar en el disco
$p->stopBuffering();
}
} catch (
Exception $e) {
echo
'No se pudo abrir Phar: ',$e;
}
?>

Además, la verificación del contenido de ficheros phar se puede realizar utilizando cualquiera de los algoritmos hash simétricos soportados (MD5, SHA1, SHA256 y SHA512 si la extensión Hash está habilitada) y utilizando firmas de clave pública/privada asimétricas de OpenSSL (nuevo en Phar 2.0.0). Para aprovechar la firmas de OpenSSL, se necesita generar una pareja de claves pública/privada, y utilizar la clave privada para establecer la firma usandoPhar::setSignatureAlgorithm(). Además, la clave pública se extrae usando este código:

<?php
$public
=openssl_get_publickey(file_get_contents('private.pem'));
$pkey='';
openssl_pkey_export($public,$pkey);
?>
debe ser guardada junto al archivo phar que verifica. Si el archivo phar es guardado como/ruta/a/mi.phar, la clave pública debe guardarse como/ruta/a/mi.phar.pubkey, o phar no será capaz de verificar la firma OpenSSL.

A partir de la verisón 2.0.0, la clasePhartambién proporciona tres métodos estáticos,Phar::webPhar(),Phar::mungServer()yPhar::interceptFileFuncs(), los cuales son cruiciales para empaquetar aplicaciones PHP diseñadas para un uso en sistemas de ficheros normales y aplicación basadas en web.Phar::webPhar()implementa un controlador principal que direcciona llamadas HTTP a la ubicación correcta dentro del archivo phar.Phar::mungServer()se utiliza para modificar los valores del array$_SERVERpara hacer que las aplicaciones procesen estos valores.Phar::interceptFileFuncs()ordena a Phar que intercepte llamdas afopen(),file_get_contents(),opendir(), y a todas las funciones basadas en estadísticas (file_exists(),is_readable(), etc.) y direccione todas las rutas relativas a las ubicaciones dentro del archivo phar.

Como ejemplo, empaquetar una versión de la popular aplicación phpMyAdmin para usarla cono un archivo phar, requiere solamente este sencillo script, y después se puede acceder aphpMyAdmin.phar.tar.phpcomo un fichero normal desde el servidor web después de modificar el usuario/contraseña:

<?php
@unlink('phpMyAdmin.phar.tar.php');
copy('phpMyAdmin-2.11.3-english.tar.gz','phpMyAdmin.phar.tar.php');
$a= newPhar('phpMyAdmin.phar.tar.php');
$a->startBuffering();
$a["phpMyAdmin-2.11.3-english/config.inc.php"] ='<?php
/* Servers configuration */
$i = 0;

/* Server localhost (config:root) [1] */
$i++;
$cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
$cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
$cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
$cfg[\'Servers\'][$i][\'compress\'] = false;
$cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
$cfg[\'Servers\'][$i][\'user\'] = \'root\';
$cfg[\'Servers\'][$i][\'password\'] = \'\';


/* End of servers configuration */
if (strpos(PHP_OS, \'WIN\') !== false) {
$cfg[\'UploadDir\'] = getcwd();
} else {
$cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
@mkdir(\'/tmp/pharphpmyadmin\');
@chmod(\'/tmp/pharphpmyadmin\', 0777);
}'
;
$a->setStub('<?php
Phar::interceptFileFuncs();
Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
echo "phpMyAdmin está intentando ejecutarse desde un navegador web\n";
exit -1;
__HALT_COMPILER();
'
);
$a->stopBuffering();
?>



Utilizar Archivos Phar: la envoltura de flujos phar

La envoltura de flujos phar soporta completamentefopen()para leer y escribir (no añadir),unlink(),stat(),fstat(),fseek(),rename()y operaciones de flujo de directoriosopendir()y a partir de la versión 2.0.0,rmdir()ymkdir().

También se pueden manipular compresiones de ficheros individuales y metadatos por fichero en un archivo Phar usando contextos de flujo:

<?php
$contexto
=stream_context_create(array('phar'=>
array(
'compress'=>Phar::GZ)),
array(
'metadata'=> array('user'=>'cellog')));
file_put_contents('phar://mi.phar/fichero.php',0,$contexto);
?>

La envoltura de flujospharno opera sobre ficheros remotos, y no puede operar sobre ficheros remotos, and cannot operate on remote files, and so is allowed even when theallow_url_fopenandallow_url_includeINI options are disabled.

Aunque es posible crear archivos phar desde cero simplemente usando operaciones de flujos, es mejor utilizar la funcionalidad interna de la clase Phar. La envoltura de flujos se usa mejor para operaciones de sólo lectura.



Utilizar Archivos Phar: las clases Phar y PharData

La clasePharadmite la lectura y la manipulación de archivos Phar, así como la iteración a través de la funcionalidad de la claseRecursiveDirectoryIterator. Con el soporte para la interfazArrayAccess, se puede acceder a los ficheros que están dentro de un archivo Phar como si fueran parte de un array asociativo.

La clasePharDataextiende la clasePhar, y permite crear y modificar archivos tar y zip no ejecutables (datos) incluso siphar.readonly=1 en php.ini. Por lo tanto,PharData::setAlias()yPharData::setStub()están desactivados ya que los conceptos de alias y rutina de interoperabilidad (stub) son válidos únicamente para archivos phar ejecutables.

Observe que al crear un archivo Phar, se debería pasar la ruta completa al contructor del objeto de la clasePhar. Las rutas relativas causarán un error en la inicialización.

Asumiendo que$pes un objeto de la clase Phar inicializado como sigue:

<?php
$p
= newPhar('/ruta/a/miphar.phar',0,'miphar.phar');
?>

se creará un archivo Phar vacío en/ruta/a/miphar.phar, o si/ruta/a/miphar.pharya existe, se abrirá de nuevo. El literalmiphar.phardemuestra el concepto de un alias que puede ser usado para referenciar a/ruta/a/miphar.pharen URLs, como en:

<?php
// estas dos llamadas a file_get_contents() son equivalentes si
// /ruta/a/miphar.phar tiene un alias especificado como "miphar.phar"
// en su manifiesto, o si el phar fue inicializado con la
// configuración del objeto Phar del ejemplo anterior
$f=file_get_contents('phar:///ruta/a/miphar.phar/loquesea.txt');
$f=file_get_contents('phar://miphar.phar/loquesea.txt');
?>

Con el recién creado objeto$pde la clasePhar, lo siguiente es posible:

  • $a = $p['fichero.php']creates aPharFileInfoclass that refers to the contents ofphar://miphar.phar/fichero.php
  • $p['fichero.php'] = $vcrea un nuevo fichero (phar://miphar.phar/fichero.php), o sobrescribe un fichero existente dentro demiphar.phar.$vpuede ser una cadena o un puntero de fichero abierto, en cuyo caso todo el contenido del fichero se usará para crear el nuevo fichero. Observe que$p->addFromString('fichero.php', $v)es funcionalmente equivalente a lo de más arriba. También es posible añadir el contenido de un fichero con$p->addFile('/path/to/fichero.php', 'fichero.php'). Por ultimo, se puede crear un directorio vacío con$p->addEmptyDir('vacio').
  • isset($p['fichero.php'])se puede usar para determinar siphar://miphar.phar/fichero.phpexiste dentro demiphar.phar.
  • unset($p['fichero.php'])borraphar://miphar.phar/fichero.phpdemiphar.phar.

Además, el objeto de la clasePhares la única manera de acceder a metainformación específica de Phar, a través dePhar::getMetadata(), y la única manera de establecer o recuperar una rutina de interoperabilidad (stub) del cargador de PHP de un archivo Phar a través dePhar::getStub()yPhar::setStub(). Además, la compresión del archivo completo Phar de una vez, sólo puede ser manipulada utilizando la clasePhar.

La lista completa de la funcionalidad de objetos de la clasePharestá documentada más adelante.

La clasePharFileInfoextiende a la claseSplFileInfo, y añade varios métodos para manipular detalles específicos de Phar de un fichero contenido en un Phar, tales como la manipulación de la compresión y la metainformación.




Creación de archivos Phar

Tabla de contenidos


Creación de archivos Phar: Introducción

Para ser escrita completamente en un futuro próximo. Antes de leer esto, asegúrese de leerComo utilizar archivos PHAR.

Un buen lugar para empezar es leer acerca dePhar::buildFromIterator(), y los detalles de la elección delformato de ficherodisponible para los archivos. Una adecuada comprensión de lo que es y hace una rutina de interoperabilidad (stub), es crucial para la creación de un archivo PHAR, asíPhar::setStub()yPhar::createDefaultStub()son buenos lugares para comenzar. Si va a distribuir una aplicación basada en web es fundamental saber qué es y cómo funcionaPhar::webPhar()y el método relacionadoPhar::mungServer(). Cualquier aplicación que tenga acceso a sus propios ficheros también debe considerar el uso dePhar::interceptFileFuncs().




¿Qué hace de un phar un phar y no un tar o un zip?

Tabla de contenidos


Ingredientes de todos los archivos Phar, independientes del formato de fichero

Todos los archivos Phar contienen tres o cuatro secciones:

  1. una rutina de interoperabilidad (stub)

  2. un manifiesto describiendo el contenido

  3. el contenido de ficheros

  4. [opcional] una firma para verificar la integridad del Phar (solamente el formtado de fichero phar)



Rutina de interoperabilidad del fichero Phar

Una rutina de interoperabilidad de un Phar es un simple fichero PHP. La rutina de interoperabilidad más pequeña posible es:

<?php__HALT_COMPILER();

Una rutina de interoperabilidad debe contener como mínimo el token__HALT_COMPILER();en su conclusión. Normalmente, una rutina de interoperabilidad contendrá funcionalidad cargadora como:

<?php
Phar
::mapPhar();
include
'phar://miphar.phar/index.php';
__HALT_COMPILER();

No existen restricciones para el contenido de una rutina de interoperabilidad de Phar, excepto el requerimiento de que concluya con__HALT_COMPILER();. La etiqueta de cierre de PHP

?>
se puede incluir u omitir, pero no puede haber más de un espacio entre el;y la etiqueta de cierre
?>
o la extensión phar no podrá procesar el manifiesto del archivo Phar.

En un archivo phar basado en tar o zip, la rutina de interoperabilidad es alamcenada en el fichero.phar/stub.php. La rutina de interoperabilidad predeterminada para archivos Phar basados en phar contiene aproximadamente 7k de código para extraer el contenido del phar y ejecutarlo. VéasePhar::createDefaultStub()para más información.

El alias de phar se alamcena en un archivo phar basado en zip en el fichero.phar/alias.txtcomo texto plano.



Comparación cara a cara de Phar, Tar y Zip

¿Cuáles son los aspectos positivos y negativos de los tres formatos de fichero soportados en la extensión phar? Esta tabla intenta responder esta pregunta.

Matriz de características: Phar contra Tar contra Zip
CaracterísticaPharTarZip
Formato de Fichero EstádarNo
Puede ser ejecutado con la extensión Phar[1]NoNo
Compresión por ficheroNo
Compresión de archivo enteroNo
Validación de firmas del archivo enteroSí (PHP 5.3.1+)
Soporte para aplicaciones específicas de web
Metainformación por fichero
Metainformación del archivo entero
Modificación creación de archivos[2]
Soporte completa para todas las funciones de envoltura de flujos
Puede ser creado/modificado incluso si phar.readonly=1[3]No

Sugerencia

[1] PHP solamente puede acceder directamente al contenido de un archivo Phar sin la extensión Phar si está utilizando unarutina de interoperabilidadque extraiga el contenido del archivo phar. La rutina de interoperabilidad creada porPhar::createDefaultStub()extrae el archivo phar y ejecuta su contenido desde un directorio temporal si no se encuentra la extensión phar.

Sugerencia

[2] Todos los accesos de escritura requieren quephar.readonlysea deshabilitado en php.ini o directamente or la línea de comandos.

Sugerencia

[3] Solamente se pueden crear archivos tar y zip sin.pharen su nombre de fichero y sin una rutina de interoperabilidad ejecutable.phar/stub.phpsi phar.readonly=1.



Archivos phar basados en tar

Los archivos basados en el formato de fichero tar siguen el formato de fichero USTAR más moderno. El diseño de la cabecera de fichero tar los hace más eficientes en el acceso que el formato de fichero zip, y casi tan efiniciente que el formato de fichero phar. Los nombres de fichero están limitados a 255 bytes, incluyentdo la ruta completa dentro de archivo phar. No existe límite en el número de ficheros que un archivo phar basado en tar puede contener. Estos archivos pueden ser comprimidos completamente en los formatos gzip o bzip2 y aún ser ejecutados por la extensión Phar.

Para comprimir un archivo entero, usePhar::compress(). Para descomprimir un archvo entero, usePhar::decompress().



Archivos phar basados en zip

Los archivos basados en el formato de fichero zip soportan varias característica incorporadas del formato de fichero zip. La metainformación por fichero y del archivo entero es almacenda en el comentario del fichero zip y en el comentario del archivo zip como una cadena serializada. Los comentarios zip preexistentes serán leídos de manera satisfactoria como una cadena. La lectura/escritura de la compresión por fichero está soportada con la compresión zlib, y el acceso a lectura está soportado con la compresión bzip2. No existe límite en el número de ficheros que un archivo phar basado en zip puede contener. Los directorios vacíos son almacenados en el archivo zip como ficheros con una barra al final, comomi/directorio/



El Formato de Fichero Phar

El formato de fichero phar está dispuesto literalmente como rutina_de_interoperabilidad/manifiesto/contenido/firma, y almacena la información crucial de lo que está incluido en el archivo phar en sumanifiesto.

El manifiesto de phar es un formato altamente optimizado que permite especificaciones por fichero de compresión de ficheros, permisos de ficheros, e incluso metainformación definida por el usuario como el usuario o grupo del fichero. Todos los valores mayores que 1 byte son almacenados en el orden de byte little-endian, con la excepción de la versión de la API, que por motivos históricos es almacenada como 3 en el orden big-endian.

Todas las banderas sin utilizar están reservadas para un uso futuro, y no deben usarse para almacenar información personalizada.to store custom information. Use la característica de metainformación por fichero para alamacenar información personalizada sobre ficheros en particular.

El formato de fichero básico de un manifiesto Phar es como sigue:

Formato del manifiesto global de Phar
Tamaño en bytesDescripción
4 bytesLongitud del manifiesto en bytes (límite 1 MB)
4 bytesNúmero de ficheros en el Phar
2 bytesVersión de la API del manifiesto de Phar (actualmente 1.0.0)
4 bytesBanderas mapeadas en bit globales de Phar
4 bytesLongitud del alisa del Phar
??Alias del Phar (la longitud basada en lo anterior)
4 bytesLongitud de la metainformación del Phar (0para ninguna)
??Metainformación de Phar serializada, almacenada en el formato deserialize()
al menos 24 * número de entradas bytesentradas para cada fichero



Banderas mapeadas en bit globales de Phar

Aquí están las banderas mapeadas en bit actualmente reconocidas por la extensión Phar para el mapeo de bit plano global de Phar:

Valores de mapeo de bit reconocidos
ValorDescripción
0x00010000Si se establece, el Phar contendrá una firma de verificaición
0x00001000Si se establece, el Phar contendrá al menos 1 fichero que está comprimido con la compresión zlib
0x00002000Si se establece, el Phar contendrá al menos 1 fichero que está comprimido con la compresión bzip



Definición de la entrada de fichero del manifiesto de Phar

Cada fichero en el manifiesto contiene la siguiente información:

Entrada de fichero del manifiesto de Phar
Tamaño en bytesDescripción
4 bytesLongitud del nombre del fichero en bytes
??Nombre del fichero (la longitud especificada en lo anterior)
4 bytesTamaño del fichero sin comprimir en bytes
4 bytesMarca de tiempo Unix del fichero
4 bytesTamaño del fichero comprimido en bytes
4 bytesSuma de verificación CRC32 del contenido del fichero si comprimir
4 bytesBanderas mapeadas en bit específicas del fichero
4 bytesLongitud de la metainformación del fichero serializada (0para ninguna)
??Metainformación del fichero serializada, almacenada en el formato deserialize()

Observe que a partir de la versión 1.1.1 de la API, los directorios vacíos son almacenados como nombres de fichero con una barra al final, comomi/directorio/

Los valores de mapeo de bit específicos de fichero reconocidos son:

Valores de mapeo de bit reconocidos
ValorDescripción
0x000001FFEstos bits están reservador para la definición de los permisos de fichero específicos de un fichero. Los permisos son usados porfstat()y se pueden utilizar para recrear permisos deseados en la extracción.
0x00001000Si se establece, el fichero es comprimido con la compresión zlib
0x00002000Si se establece, el fichero es comprimido con la compresión bzip



Formato de la firma de Phar

Los archivos Phar que contienen una firma siempre la tienen añadida al final del archivo Phar después del cargador, el manifiesto y el contenido de ficheros. Los dos formatos de firma soportados en este momento son MD5 y SHA1.

Formato de firma
Longitud en bytesDescripción
16 ó 20 bytesLa firma real, 20 bytes para una firma SHA1, 16 bytes para una firma MD5, 32 bytes para una firma SHA256, y 64 bytes para una firma SHA512.
4 bytesBanderas de firma.0x0001se usa para definir una firma MD5,0x0002se usa para definir una firma SHA1,0x0004se usa para definir una firma SHA256, y0x0008se usaupara definir una firma SHA512. El soporte para las firmas SHA256 y SHA512 se introdujo con la versión 1.1.0 de la API.
4 bytesGBMBmágico usado para definir la presencia de una firma.




La clase Phar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Introducción

La clase Phar proporciona una interfaz de alto nivel para el acceso y la creación de archivos phar.

Sinopsis de la Clase

/* Métodos */
publicaddEmptyDir(string$dirname):void
publicaddFile(string$file,string$localname= ?):void
publicaddFromString(string$localname,string$contents):void
finalpublicstaticapiVersion():string
publicbuildFromDirectory(string$base_dir,string$regex= ?):array
publicbuildFromIterator(Iterator$iter,string$base_directory= ?):array
finalpublicstaticcanCompress(int$type= 0):bool
finalpublicstaticcanWrite():bool
publiccompress(int$compression,string$extension= ?):object
publiccompressFiles(int$compression):void
public__construct(string$fname,int$flags= ?,string$alias= ?)
publicconvertToData(int$format= 9021976,int$compression= 9021976,string$extension= ?):PharData
publicconvertToExecutable(int$format= 9021976,int$compression= 9021976,string$extension= ?):Phar
publiccopy(string$oldfile,string$newfile):bool
publiccount():int
finalpublicstaticcreateDefaultStub(string$indexfile= ?,string$webindexfile= ?):string
publicdecompress(string$extension= ?):object
publicdecompressFiles():bool
publicdelMetadata():bool
publicdelete(string$entry):bool
publicextractTo(string$pathto,string|array$files= ?,bool$overwrite= false):bool
publicgetAlias():?string
publicgetModified():bool
publicgetPath():string
publicgetSignature():array
publicgetStub():string
finalpublicstaticgetSupportedCompression():array
finalpublicstaticgetSupportedSignatures():array
publicgetVersion():string
publichasMetadata():bool
finalpublicstaticinterceptFileFuncs():void
publicisBuffering():bool
publicisFileFormat(int$format):bool
finalpublicstaticisValidPharFilename(string$filename,bool$executable= true):bool
publicisWritable():bool
finalpublicstaticloadPhar(string$filename,string$alias= ?):bool
finalpublicstaticmapPhar(string$alias= ?,int$dataoffset= 0):bool
finalpublicstaticmount(string$pharpath,string$externalpath):void
finalpublicstaticmungServer(array$munglist):void
publicoffsetExists(string$offset):bool
publicoffsetGet(string$offset):int
publicoffsetSet(string$offset,string$value):void
publicoffsetUnset(string$offset):bool
finalpublicstaticrunning(bool$retphar= true):string
publicsetAlias(string$alias):bool
publicsetDefaultStub(string$index= ?,string$webindex= ?):bool
publicsetMetadata(mixed$metadata):void
publicsetSignatureAlgorithm(int$sigtype,string$privatekey= ?):void
publicsetStub(string$stub,int$len= -1):bool
publicstartBuffering():void
publicstopBuffering():void
finalpublicstaticunlinkArchive(string$archive):bool
finalpublicstaticwebPhar(
    string$alias= ?,
    string$index= "index.php",
    string$f404= ?,
    array$mimetypes= ?,
    callable$rewrites= ?
):void
}

Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDirAñadir un directorio vacío al archvo phar

Descripción

publicPhar::addEmptyDir(string$dirname):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Con este método se crea un directorio vacío con la ruta dada pordirname. Este método es similar aZipArchive::addEmptyDir().

Parámetros

dirname

El nombre de directorio vacío a crear en el archivo phar

Valores devueltos

No devuelve ningún valor, se lanza una excepción en caso de error.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::addEmptyDir()

<?php
try {
$a= newPhar('/ruta/a/phar.phar');

$a->addEmptyDir('/ruta/completa/a/fichero');
// demuestra cómo se almacena este fichero
$b=$a['ruta/completa/a/fichero']->isDir();
} catch (
Exception $e) {
// manejar los errores aquí
}
?>

Ver también



Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFileAñadir un fichero desde el sistema de ficheros al archivo phar

Descripción

publicPhar::addFile(string$file,string$localname= ?):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Con este método, cualquier fichero o URL se puede añadir al arcivo phar. Si se especifica el segundo parámetro opcionallocalname, el fichero será almacenado en el archivo con el nombre dado por el parámetro, si no se usará el parámetrofilecomo la ruta para almacentar dentro del archivo. Las URLs deben tener un nombre local o se lanzará una excepción. Este método es similar aZipArchive::addFile().

Parámetros

file

La ruta completa o relativa del fichero del disco a ser añadido al archivo phar.

localname

Ruta con la que el fichero será almacenado en el archivo.

Valores devueltos

No devuelve ningún valor, se lanza una excepción en caso de error.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::addFile()

<?php
try {
$a= newPhar('/ruta/a/phar.phar');

$a->addFile('/ruta/completa/a/fichero');
// demuestra cómo se almacena este fichero
$b=$a['ruta/completa/a/fichero']->getContent();

$a->addFile('/ruta/completa/a/fichero','mi/fichero.txt');
$c=$a['mi/fichero.txt']->getContent();

// demostrar el uso de una URL
$a->addFile('http://www.ejemplo.com','ejemplo.html');
} catch (
Exception $e) {
// manejar los errores aquí
}
?>

Ver también



Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromStringAñadir un fichero desde un string al archivo phar

Descripción

publicPhar::addFromString(string$localname,string$contents):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Con este método, cuanquierl cadena se puede añadir al archivo phar. El fichero será almacenado en el archivo conlocalnamecomo su ruta. Este método es similar aZipArchive::addFromString().

Parámetros

localname

Ruta con la que el fichero será almacenado en el archivo.

contents

El contenido del fichero a almacenar

Valores devueltos

No devuelve ningún valor, se lanza una excepción en caso de error.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::addFromString()

<?php
try {
$a= newPhar('/ruta/a/phar.phar');

$a->addFromString('ruta/a/fichero.txt','mi sencillo fichero');
$b=$a['ruta/a/fichero.txt']->getContent();

// para añadir contenido desde un gestor de flujos para ficheros grandes, use offsetSet()
$c=fopen('/ruta/a/fichero_enorme.bin');
$a['fichero_grande.bin'] =$c;
fclose($c);
} catch (
Exception $e) {
// manejar los errores aquí
}
?>

Ver también



Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersionDevolver la versión de la API

Descripción

finalpublicstaticPhar::apiVersion():string

Devuelve la versión de la API del formato de fichero phar que será usado al crear phars. La extensión Phar soporta la lectura de la versión de la API 1.0.0 o superior. Se requiere la versión 1.1.0 de la API para los algoritmos hash SHA-256 y SHA-512, y la versión 1.1.1 de la API para almacenar directorios vacíos.

Parámetros

Valores devueltos

La cadena de la versión de la API como"1.0.0".

Ejemplos

Ejemplo #1 Un ejemplo dePhar::apiVersion()

<?php
echoPhar::apiVersion();
?>

El resultado del ejemplo sería:

1.1.1



Phar::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromDirectoryConstruir un archivo phar desde los ficheros de un directorio

Descripción

publicPhar::buildFromDirectory(string$base_dir,string$regex= ?):array

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Rellena un archivo phar con el contenido de un directorio. El segundo parámtro opcional es una expresión regular (pcre) que se utiliza para excluir ficheros. Cualquier nombre de fichero que coincida con la expresión regular será incluido, todos los demás serán excluidos. Para un control más exhaustivo, usePhar::buildFromIterator().

Parámetros

base_dir

La ruta completa o relativa al directorio que contiene todos los ficheros a añadir al archivo.

regex

Una expresión regular de pcre opcional que se usa para filtrar la lista de ficheros. Solamente las rutas de fichero que coincidan con la expresión regular serán incluidas en el archivo.

Valores devueltos

Phar::buildFromDirectory()devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.

Errores/Excepciones

Este método lanza una excepción de tipoBadMethodCallExceptioncuando no puede instanciar los iteradores intermos del directorio, o una excepción de tipoPharExceptionsi hubo errores al guardar el archivo phar.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::buildFromDirectory()

<?php
// crear con el alias "proyecto.phar"
$phar= newPhar('proyecto.phar',0,'proyecto.phar');
// añadir todos los ficheros del proyecto
$phar->buildFromDirectory(dirname(__FILE__) .'/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));

$phar2= newPhar('proyecto2.phar',0,'proyecto2.phar');
// añadir todos los ficheros del, incluir solamente los ficheros php
$phar2->buildFromDirectory(dirname(__FILE__) .'/proyecto','/\.php$/');
$phar2->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>

Ver también



Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromIteratorConstruir un archivo phar desde un iterador

Descripción

publicPhar::buildFromIterator(Iterator$iter,string$base_directory= ?):array

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Rellena un archivo phar desde un iterador. Están soportados dos estilos de iteradores, los iteradores que mapean el nombre de fichero dentro del phar al nombre del fichero en disco, y los iteradores como DirectoryIterator que devuelven objetos de la clase SplFileInfo. Se requiere el segundo parámetro para los iteradores que devuelven objetos de la clase SplFileInfo.

Parámetros

iter

Cualquier iterador que mapee de forma asociativa el fichero phar a la ubiciación o que devuelva objetos de la clase SplFileInfo

base_directory

Para los iteradores que devuelven objetos de la clase SplFileInfo, es la porción de cada ruta completa de fichero a eliminar cuando de añada al archivo phar

Valores devueltos

Phar::buildFromIterator()devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::buildFromIterator()con SplFileInfo

Para la mayoría de los archivos tar/zip, el archivo reflejará la distribución real de directorios, y el segundo estilo es el más útil. Por ejemplo, para crear un archivo phar que contenga los ficheros n esta distribución de muestra de directorios:

/ruta/al/proyecto/
                  config/
                         dist.xml
                         debug.xml
                  lib/
                      fichero1.php
                      fichero2.php
                  src/
                      procesa_algo.php
                  www/
                      index.php
                  cli/
                      index.php

Este código podría usarse para añadir estos ficheros al archivo phar "proyecto.phar":

<?php
// crear con el alias "proyecto.phar"
$phar= newPhar('proyecto.phar',0,'proyecto.phar');
$phar->buildFromIterator(
new
RecursiveIteratorIterator(
new
RecursiveDirectoryIterator('/ruta/al/proyecto')),
'/ruta/al/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>

El fichero proyecto.phar se puede usar inmediatamente.Phar::buildFromIterator()no establece valores como la compresión y metainformación, que se puede hacer después de crear el archivo phar.

Como observación interesante,Phar::buildFromIterator()también se puede usar para copiar el contenido de un archivo phar existente, ya que los objetos de la clase Phar descienden de la claseDirectoryIterator:

<?php
// crear con el alias "proyecto.phar"
$phar= newPhar('proyecto.phar',0,'proyecto.phar');
$phar->buildFromIterator(
new
RecursiveIteratorIterator(
new
Phar('/ruta/a/otro_phar.phar')),
'phar:///ruta/a/otro_phar.phar/ruta/al/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>

Ejemplo #2 Un ejemplo dePhar::buildFromIterator()con otros iteradores

La segunda forma de iterador se puede usar con cualquier iterador que devuelva un mapeo clave => valor, tal como un objeto de la claseArrayIterator:

<?php
// crear con el alias "proyecto.phar"
$phar= newPhar('proyecto.phar',0,'proyecto.phar');
$phar->buildFromIterator(
new
ArrayIterator(
array(
'fichero/interno.php'=>dirname(__FILE__) .'/algun_fichero.php',
'otro/fichero.jpg'=>fopen('/rota/a/archivo_grande.jpg','rb'),
)));
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>

Errores/Excepciones

Este método lanza una excepción de tipoUnexpectedValueExceptioncuando el iterador devuelve valores incorrectos, tales como una clave de tipo integer en lugar de una cadena, una excepción de tipoBadMethodCallExceptioncuando se pasa un iterador basado en SplFileInfo sin un parámetrobase_directory, o una excepción de tipoPharExceptionsi hubo errores al guardar el archivo phar.

Ver también



Phar::canCompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canCompressDevuelve si la extensión phar soporta la compresión usando zlib o bzip2

Descripción

finalpublicstaticPhar::canCompress(int$type= 0):bool

Este método debería usarse para comprobar si es posible una compresicón antes de cargar un archivo phar que contiene ficheros comprimidos.

Parámetros

type

Se puede usar tantoPhar::GZoPhar::BZ2para comprobar si la compresión es posible con un algoritmo de compresión específico (zlib o bzip2).

Valores devueltos

truesi la compresión/descompresión está disponible,falsesi no.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::canCompress()

<?php
if (Phar::canCompress()) {
echo
file_get_contents('phar://phar_comprimido.phar/fichero/interno.txt');
} else {
echo
'La compresión no está disponible';
}
?>

Ver también



Phar::canWrite

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canWriteDevolver si la extensión phar soporta la escritura y creación de archivos phar

Descripción

finalpublicstaticPhar::canWrite():bool

Este método estático determina si ha sido deshabilitado el acceso a escritura en el php.ini del sistema mediante la variable INIphar.readonly.

Parámetros

Valores devueltos

truesi el acceso a escritura esta habilitado,falsesi está deshabilitado.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::canWrite()

<?php
if (Phar::canWrite()) {
file_put_contents('phar://miphar.phar/fichero.txt','hola, qué tal');
}
?>

Ver también



Phar::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressComprimir el archivo Phar entero usando la compresión Gzip o Bzip2

Descripción

publicPhar::compress(int$compression,string$extension= ?):object

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Para archivos phar basados en tar y en phar, este método comprime el archivo entero usando la compresión gzip o bzip2. El fichero resultante puede ser procesado con el comando gunzip/bunzip, o se puede acceder a él directa y transparentemente con la extensión Phar.

Para archivos phar basados en Zip, este método falla con el lanzamiento de una excepción. La extensiónzlibdebe estar habilitada para poder comprimir con la compresión gzip, y la extensiónbzip2debe estar habilitada para poder comprimir con la compresión bzip2. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto.

Además, este método renombra automáticamente el archivo, añadiéndole.gz,.bz2o eliminado la extensión si se pasaPhar::NONEpara eliminar la compresión. De forma alternativa, se puede expecificar una extensión de fichero con el segundo parámetro.

Parámetros

compression

La compresión debe serPhar::GZoPhar::BZ2para añadir compresión, oPhar::NONEpara eliminarla.

extension

Por omisión, la extensión es.phar.gzo.phar.bz2para comprimir archivos phar, y.phar.tar.gzo.phar.tar.bz2para comprimir archivos tar. Para la descompresión, las extensiones de fichero predeterminadas son.phary.phar.tar.

Valores devueltos

Devuelve un objeto de la clasePhar.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o la extensiónbzip2no está habilitada.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::compress()

<?php
$p
= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero1.txt'] ='hola';
$p['mifichero12.txt'] ='hola';
$p1=$p->compress(Phar::GZ);// copia a /ruta/a/mi.phar.gz
$p2=$p->compress(Phar::BZ2);// copia a /ruta/a/mi.phar.bz2
$p3=$p2->compress(Phar::NONE);// excepción: /ruta/a/mi.phar ya existe
?>

Ver también



Phar::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressFilesComprime todos los ficheros del archivo Phar actual

Descripción

publicPhar::compressFiles(int$compression):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Para archivos phar basados en tar, este método lanza una excepción de tipoBadMethodCallException, ya que la compresión de ficheros individuales dentro de un archivo tar no está soportada por el formato de fichero. UsePhar::compress()para comprimir un archivo phar entero basado en tar.

Para achivos phar basados en Zip y phar, este método comprime todos los ficheros del archivo Phar usando la compresión especificada. Las extensioneszlibobzip2deben estar habilitadas para aprovechar esta característica. Además, si cualquier fichero ya está comprimido con la compresión bzip2/zlib, la extensión respectiva debe estar habilitada para poder descomprimir los ficheros antes de re-comprimirlos. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto.

Parámetros

compression

La compresión debe serPhar::GZoPhar::BZ2para añadir compresión, oPhar::NONEpara eliminarla.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o si cualquier fichero está comprimido con la compresión bzip2 y la extensiónbzip2no está habilitada.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::compressFiles()

<?php
$p
= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
foreach (
$pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach (
$pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
?>

El resultado del ejemplo sería:

string(13) "mifichero.txt"
bool(false)
bool(false)
bool(false)
string(14) "mifichero2.txt"
bool(false)
bool(false)
bool(false)
string(13) "mifichero.txt"
int(4096)
bool(false)
bool(true)
string(14) "mifichero2.txt"
int(4096)
bool(false)
bool(true)

Ver también



Phar::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__constructConstruir un objeto de archivo Phar

Descripción

publicPhar::__construct(string$fname,int$flags= ?,string$alias= ?)

Parámetros

fname

Ruta a un archivo Phar existente o para ser creado La extensión del nombre del fichero debe contener .phar.

flags

Banderas a pasar a la clase padreRecursiveDirectoryIterator.

alias

Alias con el que referirse al archivo Phar en las llamadas a funcionalidades de flujos.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi se llama dos veces, o una excepción de tipoUnexpectedValueExceptionsi no se puede abrir el archivo phar.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::__construct()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',FilesystemIterator::CURRENT_AS_FILEINFO|FilesystemIterator::KEY_AS_FILENAME,
'mi.phar');
} catch (
UnexpectedValueException $e) {
die(
'No se pudo abrir mi.phar');
} catch (
BadMethodCallException $e) {
echo
'Técnicamente esto no puede suceder';
}
// esto funciona ahora
echofile_get_contents('phar://mi.phar/ejemplo.txt');
// y funciona si hemos escrito
echofile_get_contents('phar:///ruta/a/mi.phar/ejemplo.txt');
?>



Phar::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToDataConvertir un archivo phar en un fichero tar o zip no ejecutable

Descripción

publicPhar::convertToData(int$format= 9021976,int$compression= 9021976,string$extension= ?):PharData

Este método se usa para convertir un archivo phar ejecutable en un fichero tar o zip. Para hacer del tar o zip un fichero no ejecutable, se eliminan los ficheros del phar de rutina de interoperabilidad y de alias del recién creado nuevo archivo.

Si no se especifica ningún cambio, este método lanza una excepción de tipoBadMethodCallExceptionsi el archivo está en el formato de fichero phar. Para archivos en el formato tar o zip, este método convierte el archivo en un archivo no ejecutable.

En caso de éxito, el metodo crea un nuevo archivo en disco y devuelve un objeto de la clasePharData. El archivo antiguo no se elimina del disco, y debería hacerse manualmente después de que el proceso haya finalizado.

Parámetros

format

Este parámetro debería serPhar::TARoPhar::ZIP. Si se establece anull, se conservará el formato de fichero existente.

compression

Este parámetro debería serPhar::NONEpara no comprimir el archivo completo,Phar::GZpara la compresión basada en zlib, yPhar::BZ2para la compresión basada en bzip.

extension

Este parámetro se utiliza para sobrescribir la extensión de fichero predeterminada de un archivo convertido. Observe que.pharno puede ser usado en ningún lugar del nombre de fichero de un archivo tar o zip no ejecutable.

Si se convierte a un archivo basado en tar, las extensiones predeterminadas son.tar,.tar.gz, y.tar.bz2dependiendo de la compresión especificada. Para archivos basados en zip, la extensión predetermianda es.zip.

Valores devueltos

El método devuelve un objetoPharDataen caso de éxito, y lanza una excepción en caso de error.

Errores/Excepciones

Este método lanza una excepción de tipoBadMethodCallExceptioncuando no se puede comprimir, se ha especificado un método de compresión desconocido, el archivo solicitado está almacenado en buffer conPhar::startBuffering()y no se ha cerrado conPhar::stopBuffering(), y una excepción de tipoPharExceptionsi se encontró algún problema durante el proceso de la creación de phar.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::convertToData()

Utilizar Phar::convertToData():

<?php
try {
$tarphar= newPhar('miphar.phar.tar');
// observe que miphar.phar.tar *no* está desvinculado.
// convertirlo a un formato de fichero tar no ejecutable,
// se crea miphar.tar
$tar=$tarphar->convertToData();
// convertirlo a un formato zip no ejecutable, se crea miphar.zip
$zip=$tarphar->convertToData(Phar::ZIP);
// crear miphar.tbz
$tgz=$tarphar->convertToData(Phar::TAR,Phar::BZ2,'.tbz');
// crear miphar.phar.tgz
$phar=$tarphar->convertToData(Phar::PHAR);// lanza una excepción
} catch (Exception $e) {
// manejar el error aquí
}
?>

Ver también



Phar::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToExecutableConvertir un archivo phar en otro formato de archivo phar ejecutable

Descripción

publicPhar::convertToExecutable(int$format= 9021976,int$compression= 9021976,string$extension= ?):Phar

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Este método se utiliza para convertir un archivo phar en otro formato de fichero. Por ejemplo, se puede utilizar para crear un archivo phar ejecutable basado en tar desde un archivo phar ejecutable basado en zip, o desde un archivo phar ejecutable en el formato de fichero phar. Además, se puede utilizar para aplicar la compresión al archivo completo a un archivo basado en phar o tar.

Si no se especifica ningún cambio, este método lanza una excepción de tipoBadMethodCallException

En caso de éxito, el metodo crea un nuevo archivo en disco y devuelve un objeto de la clasePharData. El archivo antiguo no se elimina del disco, y debería hacerse manualmente después de que el proceso haya finalizado.

Parámetros

format

Este parámetro debería serPhar::PHAR,Phar::TAR, oPhar::ZIP. Si se establece anull, se conservará el formato de fichero existente.

compression

Este parámetro debería serPhar::NONEpara no comprimir el archivo completo,Phar::GZpara la compresión basada en zlib, yPhar::BZ2para la compresión basada en bzip.

extension

Este parámetro se utiliza para sobrescribir la extensión de fichero predeterminada de un archivo convertido. Observe que todos los archivos phar basados en zip o en tar deben contener.pharen su extensión de fichero para poder ser procesados como un archivo phar.

Si se convierte a un archivo basado en phar, las extensiones predeterminadas son.phar,.phar.gz, o.phar.bz2dependiendo de la compresión especificada. Para archivos phar basados en tar, las extensiones predeterminadas son.phar.tar,.phar.tar.gz, y.phar.tar.bz2. Para archivos phar basados en zip, la estensión predeterminada es.phar.zip.

Valores devueltos

El método devuelve un objetoPharen caso de éxito, y lanza una excepción en caso de error.

Errores/Excepciones

Este método lanza una excepción de tipoBadMethodCallExceptioncuando no se puede comprimir, se ha especificado un método de compresión desconocido, el archivo solicitado está almacenado en buffer conPhar::startBuffering()y no se ha cerrado conPhar::stopBuffering(), una excepción de tipoUnexpectedValueExceptionsi el soporte para escritura está deshabilitado, y una excepción de tipoPharExceptionsi se encontró algún problema durante el proceso de la creación de phar.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::convertToExecutable()

Utilizar Phar::convertToExecutable():

<?php
try {
$tarphar= newPhar('miphar.phar.tar');
// convertirlo al formato de fichero phar
// observe que miphar.phar.tar *no* está desvinculado
$phar=$tarphar->convertToExecutable(Phar::PHAR);// crea miphar.phar
$phar->setStub($phar->createDefaultStub('cli.php','web/index.php'));
// crea miphar.phar.tgz
$comprimido=$phar->convertToExecutable(Phar::TAR,Phar::GZ,'.phar.tgz');
} catch (
Exception $e) {
// manejar el error aquí
}
?>

Ver también



Phar::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::copyCopiar un fichero interno de un archivo phar a otro fichero nuevo dentro del phar

Descripción

publicPhar::copy(string$oldfile,string$newfile):bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Copia un fichero interno de un archivo phar a otro fichero nuevo dentro del phar. Esta es una alternativa orientada a objetos para usarcopy()con la envoltura de flujos phar.

Parámetros

oldfile

newfile

Valores devueltos

Devuelvetrueen caso de éxito, pero es más seguro encerrar la llamada al método en un bloque try/catch y asumir el éxito si no se lanza ninguna excepción.

Errores/Excepciones

Lanza una excepción de tipoUnexpectedValueExceptionsi el fichero origen no exite, el fichero destino ya existe, el acceso a escritura está deshabilitado, la apertura de cualquiera de los dos ficheros falla, la lectura del fichero fuente falla, o una excepción de tipoPharExceptionsi la escritura de los cambios del phar falla.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::copy()

Este ejemplo muestra el uso dePhar::copy()y su equivalente con envoltura de flujos. La principal diferencia entre los dos enfoques es el manejo de errores. Todos los métodos de Phar lanzan excepciones, mientras que la envoltura de flujos utilizatrigger_error().

<?php
try {
$phar= newPhar('miphar.phar');
$phar['a'] ='hola';
$phar->copy('a','b');
echo
$phar['b'];// imprime "hola"
} catch (Exception $e) {
// manejar errores
}

// el equivalente con envoltura de flujos del código de arriba.
// Se dispara E_WARNINGS en caso de error en vez de excepciones.
copy('phar://miphar.phar/a','phar//miphar.phar/c');
echo
file_get_contents('phar://miphar.phar/c');// imprimie "hola"
?>



Phar::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::countDevuelve el número de entradas (ficheros) en el archivo Phar

Descripción

publicPhar::count():int

Parámetros

Valores devueltos

El número de archivos que contiene Phar, o0(el número cero) si no contiene.

Ejemplos

Ejemplo #1Phar::count()ejemplo

<?php
// asegurarse de que no existe
@unlink('brandnewphar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/brandnewphar.phar',0,'brandnewphar.phar');
} catch (
Exception $e) {
echo
'No se pudo crear Phar:',$e;
}
echo
'El nuevo Phar tiene '.$p->count() ." entradas\n";
$p['file.txt'] ='hi';
echo
'El nuevo Phar tiene '.$p->count() ." entradas\n";
?>

El resultado del ejemplo sería:

El nuevo Phar tiene 0 entradas
El nuevo Phar tiene 1 entradas



Phar::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::createDefaultStubCrear una rutina de interoperabilidad específica del formato de fichero phar

Descripción

finalpublicstaticPhar::createDefaultStub(string$indexfile= ?,string$webindexfile= ?):string

Este método está destinado a la creación de rutinas de interoperabilidad (stubs) específicas del formato de fichero phar, y no está destinado a ustilizarlo con archivo phar basados en tar o zip.

Los archivos Phar contienen una rutina de interoperabilidad cargadora (en inglésstub) escrita en PHP que se ejecuta cuando el archivo es ejecutado en el propio PHP mediante inclusión:

<?php
include'miphar.phar';
?>
o por simple ejecución:
php miphar.phar
    

Este método proporciona una manera simple y sencilla de crear una rutina de interoperabilidad que ejecutará un fichero inicial desde el archivo phar. Además, se pueden especificar diferentes ficheros para ejecutar el archivo phar desde la línea de comandos o a través de un servidor web. La rutina de interoperabilidad cargadora también llama aPhar::interceptFileFuncs()para permitir empaquetar de manera sencilla una aplicación PHP que accede al sistema de ficheros. Si la extensión phar no está presente, la rutina de interoperabilidad cargadora extraerá el archivo phar en un directorio temporal y después operará sobre los archivos. Una función d cierre borra los ficheros temporales a la salida.

Valores devueltos

Devuelve una cadena que contiene una rutina de interoperabildad personalizada (stub) que permite al archivo Phar creado funcionar con o sin la extensón Phar habilitada.

Errores/Excepciones

Lanza una excepción de tipoUnexpectedValueExceptionsi cualquier parámetro es mayor de 400 bytes.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::createDefaultStub()

<?php
try {
$phar= newPhar('miphar.phar');
$phar->setStub($phar->createDefaultStub('cli.php','web/index.php'));
} catch (
Exception $e) {
// manejar errores
}
?>

Ver también

  • Phar::setStub()- Establecer el cargador de PHP o la rutina de interoperabilidad de un archivo Phar
  • Phar::getStub()- Devolver el cargador de PHP o la rutina de interoperabilidad de un archivo Phar



Phar::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressDescomprimir un archivo Phar entero

Descripción

publicPhar::decompress(string$extension= ?):object

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Para archivos phar basados en tar y phar, este método descomprime el archivo entero.

Para archivos phar basados en Zip, este método este método falla con el lanzamiento de una excepción. La extensiónzlibdebe estar habilitada para descomprimir un archivo comprimido con la compresión gzip, y la extensiónbzip2debe estar habilitada para descomprimir un archivo comprimido con la compresión bzip2. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto.

Además, este método cambia automáticamente la extensión del archivo,.pharpor omisión para archivos phar, o.phar.tarpara archivos phar basados en tar. De forma alternativa, se puede expecificar una extensión de fichero con el segundo parámetro.

Parámetros

extension

Para la descompresión, las extensiones de fichero predeterminadas son.phary.phar.tar. Use este parámetro para especificar otra extensión de fichero. Observe que todos los archivos phar ejecutables deben contener.pharen su nombre de fichero.

Valores devueltos

Devuelve un objeto de la clasePhar.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o la extensiónbzip2no está habilitada.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::decompress()

<?php
$p
= newPhar('/ruta/a/mi.phar',0,'mi.phar.gz');
$p['mifichero1.txt'] ='hola';
$p['mifichero12.txt'] ='hola';
$p3=$p2->decompress();// crea /ruta/a/mi.phar
?>

Ver también



Phar::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressFilesDescomprimir todos los ficheros del archivo Phar actual

Descripción

publicPhar::decompressFiles():bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Para archivos phar basados en tar, este método lanza una excepción de tipoBadMethodCallException, ya que la compresión de ficheros individuales dentro de un archivo tar no está soportada por el formato de fichero. UsePhar::compress()para comprimir un archivo phar entero basado en tar.

Para achivos phar basados en Zip y phar, este método descomprime todos los ficheros del archivo Phar. Las extensioneszlibobzip2deben estar habilitadas para aprovechar esta característica si cualquier fichero está comprimido con la compresión bzip2/zlib. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o si cualquier fichero está comprimido con la compresión bzip2 y la extensiónbzip2no está habilitada.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::decompressFiles()

<?php
$p
= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
$p->compressFiles(Phar::GZ);
foreach (
$pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach (
$pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
?>

El resultado del ejemplo sería:

string(13) "mifichero.txt"
int(4096)
bool(false)
bool(true)
string(14) "mifichero2.txt"
int(4096)
bool(false)
bool(true)
string(13) "mifichero.txt"
bool(false)
bool(false)
bool(false)
string(14) "mifichero2.txt"
bool(false)
bool(false)
bool(false)

Ver también



Phar::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::delMetadataEliminar la metainformación global del phar

Descripción

publicPhar::delMetadata():bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Elimina la metainformación global del phar

Parámetros

Valores devueltos

Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::delMetaData()

<?php
try {
$phar= newPhar('miphar.phar');
var_dump($phar->getMetadata());
$phar->setMetadata("hola, qué tal");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (
Exception $e) {
// manejar errores
}
?>

El resultado del ejemplo sería:

NULL
string(14) "hola, qué tal"
NULL

Ver también



Phar::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::deleteBorrar un fichero dentro de un archivo phar

Descripción

publicPhar::delete(string$entry):bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Borra un fichero dentro de un archivo. Esto es el equivalente funcional de llamar aunlink()en el equivalente de envoltura de flujos, tal como se muestra en el ejemplo de abajo.

Parámetros

entry

La ruta dentro de un archivo para borrar el fichero.

Valores devueltos

Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi se produjo algún error al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::delete()

<?php
try {
$phar= newPhar('miphar.phar');
$phar->delete('desvincular/yo.php');
// esto es equivalente a:
unlink('phar://miphar.phar/desvincular/yo.php');
} catch (
Exception $e) {
// manejar errores
}
?>

Ver también



Phar::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__destructDestructs a Phar archive object

Descripción

publicPhar::__destruct()

Parámetros

Esta función no tiene parámetros.



Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::extractToExtraer el contenido de un archivo phar a un directorio

Descripción

publicPhar::extractTo(string$pathto,string|array$files= ?,bool$overwrite= false):bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Extrae todos los ficheros de un archivo phar al disco. Los ficheros y directorios extraídos conservan los mismos permisos que los almacenados en el archivo. Los parámetros opcionales permiten controlar qué ficheros serán extraídos, y si los ficheros existentes en disco podrán ser sobrescritos. El segundo parámetrofilespuede ser el nombre de un fichero o directorio a extraer, o un array de nombre de ficheros y directorios a extraer. Por omisión, este método no sobrescribirá los ficheros existentes, aunque el tercer parámetro se puede establecer a true para habilitar la sobrescritura de ficheros. Este método es similar aZipArchive::extractTo().

Parámetros

pathto

Ruta dentro de un archivo al fichero a borrar.

files

El nombre de un fichero o directorio a extraer, o un array de ficheros/directorios a extraer.

overwrite

Esteblecer atruepara habilitar la sobrescritura de ficheros existentes

Valores devueltos

Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::extractTo()

<?php
try {
$phar= newPhar('miphar.phar');
$phar->extractTo('/ruta/completa');// extraer todos los ficheros
$phar->extractTo('/otra/ruta','fichero.txt');// extraer solamente fichero.txt
$phar->extractTo('/esta/ruta',
array(
'fichero1.txt','fichero2.txt'));// extraer solamente 2 ficheros
$phar->extractTo('/tercera/ruta',null,true);// extraer todos los ficheros y sobrescribirlos
} catch (Exception $e) {
// manejar errores
}
?>

Ver también



Phar::getAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::getAliasGet the alias for Phar

Descripción

publicPhar::getAlias():?string

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returns the alias ornullif there's no alias.



Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getMetadataDevolver la metainformación de un archivo phar

Descripción

publicPhar::getMetadata():mixed

Recupera la información de un archivo. La metainformación puede ser cualquier variable de PHP que pueda ser serializada.

Parámetros

No tiene parámetros.

Valores devueltos

Cualquier variable de PHP que pueda ser serializada y almacenada como metainformación del archivo Phar, onullsi no hay metainformación almacenada.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::getMetadata()

<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.php'] ='<?php echo "hola";';
$p->setMetadata(array('bootstrap'=>'fichero.php'));
var_dump($p->getMetadata());
} catch (
Exception $e) {
echo
'No se pudo crear y/o modificar el phar:',$e;
}
?>

El resultado del ejemplo sería:

array(1) {
  ["bootstrap"]=>
  string(11) "fichero.php"
}

Ver también



Phar::getModified

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getModifiedDevolver si el phar fue modificado

Descripción

publicPhar::getModified():bool

Este método se puede usar para determinar si un phar tiene un fichero interno eliminado, o el contenido de un fichero ha cambiado de alguna forma.

Parámetros

No tiene parámetros.

Valores devueltos

truesi el phar ha sido modificado desde su apertura,falsesi no.



Phar::getPath

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Phar::getPathGet the real path to the Phar archive on disk

Descripción

publicPhar::getPath():string

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos



Phar::getSignature

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getSignatureDevolver la firma MD5/SHA1/SHA256/SHA512/OpenSSL de un archivo Phar

Descripción

publicPhar::getSignature():array

Devuelve la firma de verificación de un archivo phar en una cadena hexadecimal.

Parámetros

Valores devueltos

Un array con las firmas del archivo abierto en la clavehash, yMD5,SHA-1,SHA-256,SHA-512, oOpenSSLen la clavehash_type. Esta firma es un hash calculado sobre el contenido entero del phar, y puede ser usada para verificar la integridad del archivo. Se requiere absolutamente una firma válida de todos los archivos phar ejecutables si la variable INIphar.require_hashestá establecida a true.



Phar::getStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getStubDevolver el cargador de PHP o la rutina de interoperabilidad de un archivo Phar

Descripción

publicPhar::getStub():string

Los archivos Phar contienen una rutina de interoperabilidad cargadora (en inglésstub) escrita en PHP que se ejecuta cuando el archivo es ejecutado en el propio PHP mediante inclusión:

<?php
include'myphar.phar';
?>
o por simple ejecución:
php myphar.phar
    

Valores devueltos

Devuelve una cadena que contiene la rutina de interoperabilidad cargadora (stub) del archivo Phar actual.

Errores/Excepciones

Lanza una excepción de tipoRuntimeExceptionsi no es posible leer la rutina de interoperabilidad del archivo Phar.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::getStub()

<?php
$p
= newPhar('/ruta/a/mi.phar',0,'mi.phar');
echo
$p->getStub();
echo
"==NEXT==\n";
$p->setStub("<?php
function __autoload(
$clase)
{
include 'phar://' . str_replace('_', '/',
$clase);
}
Phar::mapPhar('miphar.phar');
include 'phar://miphar.phar/arrancar.php';
__HALT_COMPILER(); ?>"
);
echo
$p->getStub();
?>

El resultado del ejemplo sería:

<?php __HALT_COMPILER(); ?>
==NEXT==
<?php
function __autoload($clase)
{
    include 'phar://' . str_replace('_', '/', $clase);
}
Phar::mapPhar('miphar.phar');
include 'phar://miphar.phar/arrancar.php';
__HALT_COMPILER(); ?>

Ver también

  • Phar::setStub()- Establecer el cargador de PHP o la rutina de interoperabilidad de un archivo Phar
  • Phar::createDefaultStub()- Crear una rutina de interoperabilidad específica del formato de fichero phar



Phar::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::getSupportedCompressionDevolver un array de los algoritmos de compresión soportados

Descripción

finalpublicstaticPhar::getSupportedCompression():array

Parámetros

No tiene parámetros.

Valores devueltos

Devuelve un array que contienePhar::GZoPhar::BZ2, dependiendo de la disponibilidad de la extensiónzlibo de la extensiónbz2.

Ver también



Phar::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::getSupportedSignaturesDevolver un array con los tipos de firmas soportados

Descripción

finalpublicstaticPhar::getSupportedSignatures():array

Devuelve un array con los tipos de firmas soportados

Parámetros

No tiene parámetros.

Valores devueltos

Devuelve un array que contiene cualquiera de las firmasMD5,SHA-1,SHA-256,SHA-512, oOpenSSL.

Ver también



Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getVersionDevolver información de la versión del archivo Phar

Descripción

publicPhar::getVersion():string

Devuelve la versión de la API de un archvo Phar abierto.

Parámetros

Valores devueltos

La versión de la API del arcivo abierto. No se debe confundir con la versión de la API que la extensión phar cargada usará para crear nuevos phars. Cada archivo Phar tiene la versión de la API codificada dentro de su manifiesto. Véase la documentación delformato de fichero Pharpara más información.

Ver también



Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::hasMetadataDevolver si el phar tiene metainformación global

Descripción

publicPhar::hasMetadata():bool

Devuelve si el phar tiene metainformación global establecida.

Parámetros

No tiene parámetros.

Valores devueltos

Devuelvetruesi la metainformación ha sido establecida, yfalsesi no.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::hasMetadata()

<?php
try {
$phar= newPhar('miphar.phar');
var_dump($phar->hasMetadata());
$phar->setMetadata(array('cosa'=>'hola'));
var_dump($phar->hasMetadata());
$phar->delMetadata();
var_dump($phar->hasMetadata());
} catch (
Exception $e) {
// manejar errores
}
?>

El resultado del ejemplo sería:

bool(false)
bool(true)
bool(false)

Ver también



Phar::interceptFileFuncs

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::interceptFileFuncsOrdenar a phar interceptar fopen, file_get_contents, opendir, y todas las funciones relacionadas con estadísticas

Descripción

finalpublicstaticPhar::interceptFileFuncs():void

Ordena a phar interceptarfopen(),readfile(),file_get_contents(),opendir(), y todas las funciones relacionadas con estadísticas. Si cualquiera de estas tres funciones es llamada desde dentro de un archivo phar con una ruta relativa, la llamada es modificada para acceder al fichero dentro del archivo phar. Se asume que las rutas absolutas son intentos para cargar ficheros externos desde el sistema de ficheros.

Esta función hace posible ejecutar aplicaciones de PHP diseñadas para ejecutarse desde un disco duro como una aplicación phar.

Parámetros

No tiene parámetros.

Valores devueltos

Ejemplos

Ejemplo #1 Un ejemplo dePhar::interceptFileFuncs()

<?php
Phar
::interceptFileFuncs();
include
'phar://'.__FILE__.'/fichero.php';
?>

Se asume que este phar está en/ruta/a/miphar.phary que contienefichero.phpyfichero2.txt, sifichero.phpcontiene este código:

Ejemplo #2 Un ejemplo dePhar::interceptFileFuncs()

<?php
echofile_get_contents('fichero2.txt');
?>

Normalmente, PHP buscaráfichero2.txten el directorio actual, que traducirá como el directorio del fichero.php, o el direcotorio actual de un usuario de la línea de comandos. En el código del ejemplo anterior,Phar::interceptFileFuncs()ordena a PHP que considere el directorio actual comophar:///ruta/a/miphar.phar/y por lo tanto abraphar:///ruta/a/miphar.phar/fichero2.txt.



Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::isBufferingDeterminar si las operaciones de escritura de Phar está siendo almacenadas en buffer, o están siendo volcadas directamente al disco

Descripción

publicPhar::isBuffering():bool

Este método se puede usar para determinar si un Phar guardará los cambios al disco inmediatamente, o si se necesita una llamadaPhar::stopBuffering()para habilitar el guardado de los cambios.

La escritura en buffer de Phar es por archivo, el almacenamiento activo en buffer del archivo Pharfoo.pharno afecta a los cambios hechos al archivo Pharbar.phar.

Valores devueltos

Devuelvetruesi las operaciones de escritura están siendo almacenadas en buffer,falsesi no.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::isBuffering()

<?php
$p
= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p2= newPhar('phar_existente.phar');
$p['fichero1.txt'] ='hola';
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>
=2=
<?php
$p
->startBuffering();
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
$p->stopBuffering();
?>
=3=
<?php
var_dump
($p->isBuffering());
var_dump($p2->isBuffering());
?>

El resultado del ejemplo sería:

bool(false)
bool(false)
=2=
bool(true)
bool(false)
=3=
bool(false)
bool(false)

Ver también

  • Phar::startBuffering()- Iniciar las operaciones de escritura en buffer de Phar, no modifica el objeto Phar del disco
  • Phar::stopBuffering()- Detener las peticiones de escritura en buffer del archivo Phar, y guardar los cambios en disco



Phar::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isCompressedDevuelve Phar::GZ oPHAR::BZ2 si el archivo phar entero está comprimido (.tar.gz/tar.bz, etc.)

Descripción

publicPhar::isCompressed():mixed

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Devuelve Phar::GZ o PHAR::BZ2 si el archivo phar entero está comprimido (.tar.gz/tar.bz, etc.). Los archivos phar basados en Zip no pueden ser comprimidos como un fichero, y por lo tanto, este método devolverá siemprefalsesi se requiere un archivo phar basado en zip.

Parámetros

No tiene parámetros.

Valores devueltos

Phar::GZ,Phar::BZ2ofalse

Ejemplos

Ejemplo #1 Un ejemplo dePhar::isCompressed()

<?php
try {
$phar1= newPhar('miphar.zip.phar');
var_dump($phar1->isCompressed());
$phar2= newPhar('sin_comprimir.tar.phar');
var_dump($phar2->isCompressed());
$phar2->compress(Phar::GZ);
var_dump($phar2->isCompressed() ==Phar::GZ);
} catch (
Exception $e) {
}
?>

El resultado del ejemplo sería:

bool(false)
bool(false)
bool(true)

Ver también



Phar::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isFileFormatDevolver true si el archivo phar está basado en el formato de fichero tar/phar/zip dependiendo del parámetro

Descripción

publicPhar::isFileFormat(int$format):bool

Parámetros

format

Phar::PHAR,Phar::TAR, oPhar::ZIPpara comprobar el formato del archivo.

Valores devueltos

Devuelvetruesi el archivo phar coincide con el formato de fichero solicitado por el parámetro

Errores/Excepciones

Se lanza una excepción de tipoPharExceptionsi el parámetro es un especificador de formato de fichero desconocido.

Ver también



Phar::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::isValidPharFilenameDevolver si el nombre de fichero dado es un nombre de fichero phar válido

Descripción

finalpublicstaticPhar::isValidPharFilename(string$filename,bool$executable= true):bool

Devuelve si el nombre de fichero dado es un nombre de fichero phar válido que será reconocido como un archivo phar por la extensión phar. Este método se puede usar para comprobar un nombre sin tener que instanciar un archivo phar y capturar la inevitable excepción que será lanzada si se especifica un nombre no válido.

Parámetros

filename

El nombre o la ruta completa al archivo phar aún no creado

executable

Este parámetro determina si el nombre de fichero debería ser tratado como un archivo phar ejecutable o un archivo de datos no ejecutable

Valores devueltos

Devuelvetruesi el nombre de fichero es válido,falsesi no.



Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isWritableDevolver si el archivo phar se puede modificar

Descripción

publicPhar::isWritable():bool

Este método devuelvetruesiphar.readonlyes0, y el archivo phar real del disco no es de sólo lectura.

Parámetros

No tiene parámetros.

Valores devueltos

Devuelvetruesi el archivo phar puede ser modificado

Ver también



Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::loadPharCargar cualquier archivo phar con un alias

Descripción

finalpublicstaticPhar::loadPhar(string$filename,string$alias= ?):bool

Este método se puede usar para leer el contenido de una archivo Phar externo. Esto es más útil para asignar un alias a un phar, por lo que las referencias subsiguientes al phar puedan usar el alias más corto, o para cargar archivos Phar que contengan solamente datos y no estén concebidos para la ejecución/inclusión en scripts de PHP.

Parámetros

filename

La ruta completa o relativa al archivo phar a abrir

alias

El alias que puede usarse para referirse al archivo phar. Observe que muchos archivos phar especifican un alias explícito dentro del archivo phar, y que una excepción de tipoPharExceptionserá lanzada si en este caso se especifica un nuevo alias.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi se pasa un alias y en archivo phat ya tiene uno explícito

Ejemplos

Ejemplo #1 Un ejemplo dePhar::loadPhar()

Phar::loadPhar puede usarse en cualquier lugar para cargar un archivo Phar externo, mientras que Phar::mapPhar debería usarse en una rutina de interoperabilidad cargadora para un Phar.

<?php
try {
Phar::loadPhar('/ruta/a/phar.phar','mi.phar');
echo
file_get_contents('phar://mi.phar/fichero.txt');
} catch (
PharException $e) {
echo
$e;
}
?>

Ver también

  • Phar::mapPhar()- Leer el fichero (un phar) que está en ejecución y registrar su manifiesto



Phar::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::mapPharLeer el fichero (un phar) que está en ejecución y registrar su manifiesto

Descripción

finalpublicstaticPhar::mapPhar(string$alias= ?,int$dataoffset= 0):bool

Este método estático solamente se puede usar dentro de una rutina de interoperabilidad cargadora de un archivo Phar para inicializar el phar cuando sea directamente ejecutado, o cuando se incluya en otro scrip.

Parámetros

alias

El alias que puede usarse en las URLphar://para referirse a este archivo, en vez de su ruta completa.

dataoffset

Variable sin uso, está aquí por compatibilidad con los PHP_Archive de PEAR.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Se lanza una excepción de tipoPharExceptionsi no se llama directamente dentro de la ejecución de PHP, si no se encuentra el token __HALT_COMPILER(); en el fichero fuente actual, o si el fichero no se puede abrir para lectura.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::mapPhar()

mapPhar debería usarse dentro de una rutina de interoperabilidad cargadora de phar. Utilice loadPhar para cargar un phar externo en memoria.

Aquí está una rutina de interoperabilidad de Phar de muestra que usa mapPhar.

<?php
function__autoload($clase)
{
include
'phar://mi.phar/'.str_replace('_','/',$clase) .'.php';
}
try {
Phar::mapPhar('mi.phar');
include
'phar://mi.phar/inicio.php';
} catch (
PharException $e) {
echo
$e->getMessage();
die(
'No se puede inicializar el Phar');
}
__HALT_COMPILER();

Ver también



Phar::mount

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mountMontar un fichero o ruta externos en una ubicación virtual dentro de un archivo phar

Descripción

finalpublicstaticPhar::mount(string$pharpath,string$externalpath):void

Al igual que con el concepto del sistema de ficheros de Unix de montar dispositivos externos en rutas dentro del árbol de directorios,Phar::mount()siempre se refiere a ficheros y directorios externos como si estuvieran dentro de un archivo phar. Esto perimte una potente abstracción tal como referirse a ficheros de configuración externos como si estuvieran dentro del archivo.

Parámetros

pharpath

La ruta interna a usar dentro del archivo phar como la ubicación de la ruta montada. Debe ser una ruta relativa dentro del archivo phar, y no debe existir.

externalpath

Una ruta o un URL a un fichero o directorio externo a montar dentro del archivo phar.

Valores devueltos

No devuelve nada. Lanza una excepción de tipoPharExceptionen caso de fallo.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi ocurrió algún problema al montar la ruta.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::mount()

El siguiente ejemplo muestra el acceso a un fichero de configuración externo como si fuera una ruta dentro de un archivo phar.

Lo primero, el código dentro de un archivo phar:

<?php
$configuración
=simplexml_load_string(file_get_contents(
Phar::running(false) .'/config.xml'));
?>

Lo siguiente, el código externo utilizado para montar el fichero de configuración:

<?php
// primero se establece la asociación entre el config.xml abstracto
// y el real del disco
Phar::mount('phar://config.xml','/home/example/config.xml');
// ahora ejecutar la aplicación
include'/ruta/a/archivo.phar';
?>

Otro método es poner el codigo de montaje dentro de la rutina de interoperabilidad del archivo phar. Aquí está un ejemplo de establecer un fichero de configuración predeterminado si no se especifica una configuración de usuario:

<?php
// primero se establece la asociación entre el config.xml abstracto
// y el real del disco
if (defined('EXTERNAL_CONFIG')) {
Phar::mount('config.xml',EXTERNAL_CONFIG);
if (
file_exists(__DIR__.'/extra_config.xml')) {
Phar::mount('extra.xml',__DIR__.'/extra_config.xml');
}
} else {
Phar::mount('config.xml','phar://'.__FILE__.'/default_config.xml');
Phar::mount('extra.xml','phar://'.__FILE__.'/default_extra.xml');
}
// ahora ejecutar la aplicación
include'phar://'.__FILE__.'/index.php';
__HALT_COMPILER();
?>

...y el código externo para cargar este archivo phar:

<?php
define
('EXTERNAL_CONFIG','/inicio/ejemplo/config.xml');
// ahora ejecutar la aplicación
include'/ruta/a/archivo.phar';
?>



Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mungServerDefinir una lista de hasta 4 variables $_SERVER que debería ser modificadas para la ejecución

Descripción

finalpublicstaticPhar::mungServer(array$munglist):void

Phar::mungServer()solamente debería ser llamado dentro de la rutina de interoperabilidad de un archivo phar.

Define una lista de hasta 4 variables$_SERVERque deberían ser modificadas para la ejecución. Las variables que pueden ser modificadas para eliminar rastros de una ejecución de un phar sonREQUEST_URI,PHP_SELF,SCRIPT_NAMEySCRIPT_FILENAME.

Por sí solo, este método no hace nada. Solamente al combinarlo conPhar::webPhar()hace que tenga efecto, y sólo cuando el fichero solicitado es un fichero de PHP a ser procesado. Observe que las variablesPATH_INFOyPATH_TRANSLATEDson siempre modificadas.

Los valores originales de las variables que son modificadas son almacenados en el array SERVER con el prefijoPHAR_, así por ejemploSCRIPT_NAMEsería guardado comoPHAR_SCRIPT_NAME.

Parámetros

munglist

Un array que contiene como índices de cadenasREQUEST_URI,PHP_SELF,SCRIPT_NAMEySCRIPT_FILENAME. Otros valores lanzan una excepción, yPhar::mungServer()es sensible a mayúsculas-minúsculas.

Valores devueltos

No devuelve nada.

Errores/Excepciones

Lanza una excepción de tipoUnexpectedValueExceptionsi se encontró algún problema con la información pasada.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::mungServer()

<?php
// rutina de interoperabilidad de ejemplo
Phar::mungServer(array('REQUEST_URI'));
Phar::webPhar();
__HALT_COMPILER();
?>

Ver también

  • Phar::webPhar()- mapPhar para archivos phar basados en web. Controlador principal para aplicaciones web
  • Phar::setStub()- Establecer el cargador de PHP o la rutina de interoperabilidad de un archivo Phar



Phar::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetExistsDetermina si un fichero existe en un phar

Descripción

publicPhar::offsetExists(string$offset):bool

Ésta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array.

offsetExists() es llamado siempre queisset()sea llamada.

Parámetros

offset

El nombre del fichero (ruta relativa) a buscar en un Phar.

Valores devueltos

Devuelvetruesi el fichero existe dentro del phar, ofalsesi no.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::offsetExists()

<?php
$p
= newPhar(dirname(__FILE__) .'/mi.phar',0,'mi.phar');
$p['primer_fichero.txt'] ='primer fichero';
$p['segundo_fichero.txt'] ='segundo_fichero';
// las siguientes líneas llama a offsetExists() indirectamente
var_dump(isset($p['primer_fichero.txt']));
var_dump(isset($p['no_existe.txt']));
?>

El resultado del ejemplo sería:

bool(true)
bool(false)

Ver también



Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetGetObtener un objeto de la clasePharFileInfopara un fichero específico

Descripción

publicPhar::offsetGet(string$offset):int

Ésta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array.Phar::offsetGet()se usa para recuperar ficheros de un archivo Phar.

Parámetros

offset

El nombre del fichero (ruta relativa) a buscar en un Phar.

Valores devueltos

Devuelve un objeto de la clasePharFileInfoque puede usarse para iterar sobre el contenido de un fichero o para recuperar información sobre el fichero actual.

Errores/Excepciones

Este método lanza una extepción de tipoBadMethodCallExceptionsi el fichero no existe en el archivo Phar.

Ejemplos

Ejemplo #1 Ejemplo dePhar::offsetGet()

Ya que todas las clases implementan la iterfazArrayAccess,Phar::offsetGet()es automáticamente llamada a utilizar el operador[].

<?php
$p
= newPhar(dirname(__FILE__) .'/miphar.phar',0,'miphar.phar');
$p['existe.txt'] ="el fichero existe\n";
try {
// automáticamente llama a offsetGet()
echo$p['existe.txt'];
echo
$p['no_existe.txt'];
} catch (
BadMethodCallException $e) {
echo
$e;
}
?>

El resultado del ejemplo sería:

el fichero existe
Entry no_existe.txt does not exist

Ver también



Phar::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetSetEstablecer el contenido de un fichero interno a aquel de un fichero externo

Descripción

publicPhar::offsetSet(string$offset,string$value):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Ésta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array. offsetSet se utiliza para modificar un fichero existente, o añadir un nuevo fichero al archivo Phar.

Parámetros

offset

El nombre del fichero (ruta relativa) a modificar en un Phar.

value

El contenido del fichero.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Siphar.readonlyes1, lanza una excepción de tipoBadMethodCallException, ya que modificar un Phar sólo está permitido cuando phar.readonly está establecido a0. Lanza un excepción de tipoPharExceptionsi existe cualquier problema volcando los cambios hechos al archivo Phar al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::offsetSet()

No se debería acceder directamente a offsetSet, en su lugar se utiliza el operador[]para acceder al array.

<?php
$p
= newPhar('/ruta/a/mi.phar',0,'mi.phar');
try {
// llama a offsetSet
$p['fichero.txt'] ='Hola qué tal';
} catch (
Exception $e) {
echo
'No se pudo modificar fichero.txt:',$e;
}
?>

Ver también



Phar::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetUnsetEliminar un fichero de un phar

Descripción

publicPhar::offsetUnset(string$offset):bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Ésta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo Phar utilizando los corchetes de acceso al array. offsetUnset se utiliza para borrar un fichero existente, y es llamado por el constructor de lenguajeunset().

Parámetros

offset

El nombre del fichero (ruta relativa) a eliminar en un Phar.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Siphar.readonlyes1, lanza una excepción de tipoBadMethodCallException, ya que modificar un Phar sólo está permitido cuando phar.readonly está establecido a0. Lanza un excepción de tipoPharExceptionsi existe cualquier problema volcando los cambios hechos al archivo Phar al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::offsetUnset()

<?php
$p
= newPhar('/ruta/a/mi.phar',0,'mi.phar');
try {
// borra fichero.txt de mi.phar llamando a offsetUnset
unset($p['fichero.txt']);
} catch (
Exception $e) {
echo
'No se pudo borrar fichero.txt: ',$e;
}
?>

Ver también



Phar::running

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::runningDevolover la ruta completa del disco o el URL completo de phar del archivo Phar que está en ejecución

Descripción

finalpublicstaticPhar::running(bool$retphar= true):string

Devuelve la ruta completa del archivo phar en ejecución. Este método tiene la intención de utilizarse como la constante mágica__FILE__, y solamente tiene efecto dentro de un archivo phar en ejecución.

Dentro de una rutina de interoperabilidad de un archivo,Phar::running()devuelve"". Use simplemente__FILE__para acceder al phar que está ejecutándose acualmente dentro de una rutina de interoperabilidad.

Parámetros

retphar

Si esfalse, se devuelve la ruta completa del disco del archivo phar. Si estrue, se devuelve el URL phar completo.

Valores devueltos

Devuelve el nombre de fichero si es válido, si no una cadena vacía.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::running()

Para el siguiente ejemplo se asume que el archivo phar está ubicado en/ruta/a/phar/mi.phar.

<?php
$a
=Phar::running();// $a es "phar:///ruta/a/mi.phar"
$b=Phar::running(false);// $b es "/ruta/a/mi.phar"
?>



Phar::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::setAliasEstablecer el alias para un archivo Phar

Descripción

publicPhar::setAlias(string$alias):bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Establece el alias par un archivo Phar, y lo escribe como el alias permanente para este archivo phar. Un alias puede usarse internamente a un archivo phar para asegurarse de que el uso de la envoltura de flujopharpara acceder a ficheros internos, siempre funcione sin tener en cuenta la ubicación del archivo phar en el sistema de ficheros. Otra alternativa es confiar en la intercepción de Phar deincludeo utilizarPhar::interceptFileFuncs()y usar rutas relativas.

Parámetros

alias

Una cadena abreviada para referirse a este archivo en el acceso con la envoltura de flujophar.

Valores devueltos

Errores/Excepciones

Lanza una excepción de tipoUnexpectedValueExceptioncuando el acceso a escritura está deshabilitado, y una excepción de tipoPharExceptionsi el alias ya está en uso o se encontró algún problema al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::setAlias()

<?php
try {
$phar= newPhar('miphar.phar');
$phar->setAlias('mip.phar');
} catch (
Exception $e) {
// manejar errores
}
?>

Ver también



Phar::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::setDefaultStubEstablecer el cargador o la rutina de interoperabilidad de un archivo Phar al cargador predeterminado

Descripción

publicPhar::setDefaultStub(string$index= ?,string$webindex= ?):bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Este método es un método cómodo que combina la funcionalidad dePhar::createDefaultStub()yPhar::setStub().

Parámetros

index

La ruta relativa dentro del archivo phar a ejectuar si se accede desde la línea de comandos

webindex

La ruta relativa dentro del archivo phar a ejectuar si se accede desde un servidor web

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Se lanza una excepción de tipoUnexpectedValueExceptionsiphar.readonlyestá habilitado en php.ini. Se lanza una excepción de tipoPharExceptionsi se encuentra cualquier problema al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::setDefaultStub()

<?php
try {
$phar= newPhar('miphar.phar');
$phar->setDefaultStub('cli.php','web/index.php');
// esto es lo mismo que:
// $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
// manejar errores
}
?>

Ver también

  • Phar::setStub()- Establecer el cargador de PHP o la rutina de interoperabilidad de un archivo Phar
  • Phar::createDefaultStub()- Crear una rutina de interoperabilidad específica del formato de fichero phar



Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadataEstablecer la metainformación de un archivo phar

Descripción

publicPhar::setMetadata(mixed$metadata):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Phar::setMetadata()debería usarse para almacenar información personalizada que describa algo sobre el archivo phar como una entidad completa.PharFileInfo::setMetadata()debería usarse para metainformación específica de cada fichero. La metainformación puede ralentizar la velocidad de carga de un archivo phar si la información es grande.

Algunos posibles usos para la metainformación incluyen especificar qué fichero dentro del archivo debería usarse para cargar el archivo, o la ubicación de un fichero de manifiesto como el fichero package.xml de» PEAR. Sin embargo, se puede almacenar cualquier información útil que describa el archivo phar.

Parámetros

metadata

Cualquier variable de PHP que contenga la información a almacenar que describa el archivo phar

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::setMetadata()

<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.php'] ='<?php echo "hola"';
$p->setMetadata(array('bootstrap'=>'fichero.php'));
var_dump($p->getMetadata());
} catch (
Exception $e) {
echo
'No se pudo crear y/o modificar el phar:',$e;
}
?>

El resultado del ejemplo sería:

array(1) {
  ["bootstrap"]=>
  string(11) "fichero.php"
}

Ver también



Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithmEstablecer el algoritmo de firma para un phar y aplicarlo

Descripción

publicPhar::setSignatureAlgorithm(int$sigtype,string$privatekey= ?):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Establece el algoritmo de firma para un phar y lo aplica. El algoritmo de firma debe ser una de las constantesPhar::MD5,Phar::SHA1,Phar::SHA256,Phar::SHA512, oPhar::OPENSSL.

Observe que todos los archivos phar ejecutables tienen una firma creada automáticamente,SHA1por omisión. Los archivos de datos basados en tar o en zip (archivos creados con la clasePharDataclass) deben tener su signatura creada y establecerla explícitamente mediantePhar::setSignatureAlgorithm().

Parámetros

sigtype

Una de las constantesPhar::MD5,Phar::SHA1,Phar::SHA256,Phar::SHA512, oPhar::OPENSSL

privatekey

El contenido de una clave privada OpenSSL, como la extraída de un certificado o de un fichero de clave OpenSSL:

<?php
$private
=openssl_get_privatekey(file_get_contents('private.pem'));
$pkey='';
openssl_pkey_export($private,$pkey);
$p->setSignatureAlgorithm(Phar::OPENSSL,$pkey);
?>
Véase laIntroducción de pharpara instrucciones sobre la designación y ubicaión del fichero de clave pública.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Lanza una excepción de tipoUnexpectedValueExceptionpara muchos errores, y una excepción de tipoPharExceptionsi ocurrió algún problema al volcar los cambios al disco.

Ver también



Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStubEstablecer el cargador de PHP o la rutina de interoperabilidad de un archivo Phar

Descripción

publicPhar::setStub(string$stub,int$len= -1):bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Este método se utiliza para añadir una rutina de interoperabilidad cargadora a un nuevo archivo Phar, o reemlazar la rutina de interoperabilidad de un archivo Phar existente.

La rutina de interoperabilidad cargadora de un archivo Phar se utiliza siempre que un archivo esté incluido directamente como en este ejemplo:

<?php
include'miphar.phar';
?>

Al cargador no se accede cuando se incluye un archivo a través de la envoltura de flujospharcomo aquí:

<?php
include'phar://miphar.phar/un_fichero.php';
?>

Parámetros

stub

Una cadena o un gestor de flujo abierto para usarlo como la rutina de interoperabilidad ejecutable de este archivo phar.

len

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Se lanza una excepción de tipoUnexpectedValueExceptionsiphar.readonlyestá habilitado en php.ini. Se lanza una excepción de tipoPharExceptionsi se encuentra cualquier problema al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::setStub()

<?php
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['a.php'] ='<?php var_dump("Hola");';
$p->setStub('<?php var_dump("Primero"); Phar::mapPhar("nuevo_phar.phar"); __HALT_COMPILER(); ?>');
include
'phar://nuevo_phar.phar/a.php';
var_dump($p->getStub());
$p['b.php'] ='<?php var_dump("Mundo");';
$p->setStub('<?php var_dump("Segundo"); Phar::mapPhar("nuevo_phar.phar"); __HALT_COMPILER(); ?>');
include
'phar://nuevo_phar.phar/b.php';
var_dump($p->getStub());
} catch (
Exception $e) {
echo
'Las operaciones de escritura sobre nuevo_phar.phar fallaron: ',$e;
}
?>

El resultado del ejemplo sería:

string(4) "Hola"
string(84) "<?php var_dump("Primero"); Phar::mapPhar("nuevo_phar.phar"); __HALT_COMPILER(); ?>"
string(5) "Mundo"
string(84) "<?php var_dump("Segundo"); Phar::mapPhar("nuevo_phar.phar"); __HALT_COMPILER(); ?>"

Historial de cambios

VersiónDescripción
5.4.0Se añadió el parámetrolen.

Ver también

  • Phar::getStub()- Devolver el cargador de PHP o la rutina de interoperabilidad de un archivo Phar
  • Phar::createDefaultStub()- Crear una rutina de interoperabilidad específica del formato de fichero phar



Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::startBufferingIniciar las operaciones de escritura en buffer de Phar, no modifica el objeto Phar del disco

Descripción

publicPhar::startBuffering():void

Aunque es técnicamente innecesario, el métodoPhar::startBuffering()puede proporcionar un aumento significativo de rendimiento al crear o modificar un archivo Phar con un gran número de ficheros. Normalmente, cada vez que un fichero dentro de un archivo Phar es creado o modificado de alguna manera, el archivo Phar entero se re-creará con los cambios. De esta forma, el archivo estará actualizado con la actividad realizada sobre él.

Sin embargo, esto puede ser innecesario al crear simplemente un nuevo archivo Phar, que tendría más sentido escribir el archivo entero de una vez. De forma similar, a menudo es necesario realizar una serie de cambios y asegurarse de que todos son posibles antes de hacer cualquier cambio en disco, similar al concepto de transacciones en bases de datos relacionales. La pareja de métodosPhar::startBuffering()/Phar::stopBuffering()está prevista para este propósito.

La escritura en buffer de Phar es por archivo, el almacenamiento activo en buffer del archivo Pharfoo.pharno afecta a los cambios hechos al archivo Pharbar.phar.

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::startBuffering()

<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
} catch (
Exception $e) {
echo
'No se pudo crear el phar:',$e;
}
echo
'El nuevo phar tiene '.$p->count() ." entradas\n";
$p->startBuffering();
$p['fichero.txt'] ='hola';
$p['fichero2.txt'] ='qué tal';
$p['fichero2.txt']->setCompressedGZ();
$p['fichero3.txt'] ='cara de niño';
$p['fichero3.txt']->setMetadata(42);
$p->setStub("<?php
function __autoload(
$clase)
{
include 'phar://miphar.phar/' . str_replace('_', '/',
$clase) . '.php';
}
Phar::mapPhar('miphar.phar');
include 'phar://miphar.phar/inicio.php';
__HALT_COMPILER();"
);
$p->stopBuffering();
?>

Ver también

  • Phar::stopBuffering()- Detener las peticiones de escritura en buffer del archivo Phar, y guardar los cambios en disco
  • Phar::isBuffering()- Determinar si las operaciones de escritura de Phar está siendo almacenadas en buffer, o están siendo volcadas directamente al disco



Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::stopBufferingDetener las peticiones de escritura en buffer del archivo Phar, y guardar los cambios en disco

Descripción

publicPhar::stopBuffering():void

Phar::stopBuffering()se usa junto con el métodoPhar::startBuffering().Phar::startBuffering()puede proporcionar un aumento significativo de rendimiento al crear o modificar un archivo Phar con un gran número de ficheros. Normalmente, cada vez que un fichero dentro de un archivo Phar es creado o modificado de alguna manera, el archivo Phar entero se re-creará con los cambios. De esta forma, el archivo estará actualizado con la actividad realizada sobre él.

Sin embargo, esto puede ser innecesario al crear simplemente un nuevo archivo Phar, que tendría más sentido escribir el archivo entero de una vez. De forma similar, a menudo es necesario realizar una serie de cambios y asegurarse de que todos son posibles antes de hacer cualquier cambio en disco, similar al concepto de transacciones en bases de datos relacionales. La pareja de métodosPhar::startBuffering()/Phar::stopBuffering()está prevista para este propósito.

La escritura en buffer de Phar es por archivo, el almacenamiento activo en buffer del archivo Pharfoo.pharno afecta a los cambios hechos al archivo Pharbar.phar.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Se lanza una excepción de tipoPharExceptionsi se encontró algún problema volcando los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::stopBuffering()

<?php
$p
= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero1.txt'] ='hola';
$p->startBuffering();
var_dump($p->getStub());
$p->setStub("<?php
function __autoload(\$clase)
{
include 'phar://nuevo_phar.phar/' . str_replace('_', '/', \$clase) . '.php';
}
Phar::mapPhar('nuevo_phar.phar');
include 'phar://nuevo_phar.phar/incio.php';
__HALT_COMPILER();"
);
$p->stopBuffering();
var_dump($p->getStub());
?>

El resultado del ejemplo sería:

string(24) "<?php __HALT_COMPILER();"
string(195) "<?php
function __autoload($clase)
{
    include 'phar://' . str_replace('_', '/', $clase);
}
Phar::mapPhar('nuevo_phar.phar');
include 'phar://nuevo_phar.phar/incio.php';
__HALT_COMPILER();"

Ver también

  • Phar::startBuffering()- Iniciar las operaciones de escritura en buffer de Phar, no modifica el objeto Phar del disco
  • Phar::isBuffering()- Determinar si las operaciones de escritura de Phar está siendo almacenadas en buffer, o están siendo volcadas directamente al disco



Phar::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::unlinkArchiveElimiar completamente un archivo phar del disco y de la memoria

Descripción

finalpublicstaticPhar::unlinkArchive(string$archive):bool

Elimina un archivo phar del disco y de la memoria.

Parámetros

archive

La ruta en el disco al archivo phar.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Se lanza una excepción de tipoPharExceptionsi existe cualquier fichero abierto que apunte al archivo phar, o cualquier objeto existente de las clasesPhar,PharData, oPharFileInfoque haga referencia al archivo phar.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::unlinkArchive()

<?php
// uso simple
Phar::unlinkArchive('/ruta/a/mi.phar');

// ejemplo más común:
$p= newPhar('mi.phar');
$fp=fopen('phar://mi.phar/fichero.txt','r');
// esto crea 'mi.phar.gz'
$gp=$p->compress(Phar::GZ);
// eliminar todas las referencias al archivo
unset($p);
fclose($fp);
// ahora, eliminar todas los indicions del archivo
Phar::unlinkArchive('mi.phar');
?>

Ver también



Phar::webPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::webPharmapPhar para archivos phar basados en web. Controlador principal para aplicaciones web

Descripción

finalpublicstaticPhar::webPhar(
    string$alias= ?,
    string$index= "index.php",
    string$f404= ?,
    array$mimetypes= ?,
    callable$rewrites= ?
):void

Phar::mapPhar()para archivos phar basados en web. Este método procesa$_SERVER['REQUEST_URI']y direcciona una petición de un navegador web a un fichero interno dentro de un archivo phar. En esencia, simula un servidor web, direccionando las peticiones al fichero correcto, enviando las cabeceras correctas y procesando ficheros PHP según sea necesario. Este poderoso método es parte de lo que hace sencillo convertir una apliación PHP existene en un archivo phar. Combinado conPhar::mungServer()yPhar::interceptFileFuncs(), cualquier aplicación web se puede utilizar sin modificaciones desde un archivo phar.

Phar::webPhar()debería llamarse solamente desde la rutina de interoperabilidad (stub) de un archivo phar (aquíhay más información de lo que es una rutina de interorperabilidad).

Parámetros

alias

El alias que puede usarse en las URLphar://para referirse a este archivo, en vez de su ruta completa.

index

La ubicación dentro del phar del índice de directorios.

f404

La ubicación del script a ejecutar cuando no se encuentra el fichero. Este script debería mostrar las cabeceras HTTP 404 apropiadas.

mimetypes

Un array que mapea extensiones de fichero adicionales a tipos de MIME. Si el mapeo predeterminado es suficiente, se ha de pasar un array vacío. Por omisión, estas extensiones son mapeadas a estos tipos de MIME:

<?php
$mimes
= array(
'phps'=>Phar::PHPS,// pasa a highlight_file()
'c'=>'text/plain',
'cc'=>'text/plain',
'cpp'=>'text/plain',
'c++'=>'text/plain',
'dtd'=>'text/plain',
'h'=>'text/plain',
'log'=>'text/plain',
'rng'=>'text/plain',
'txt'=>'text/plain',
'xsd'=>'text/plain',
'php'=>Phar::PHP,// procesado como PHP
'inc'=>Phar::PHP,// procesado como PHP
'avi'=>'video/avi',
'bmp'=>'image/bmp',
'css'=>'text/css',
'gif'=>'image/gif',
'htm'=>'text/html',
'html'=>'text/html',
'htmls'=>'text/html',
'ico'=>'image/x-ico',
'jpe'=>'image/jpeg',
'jpg'=>'image/jpeg',
'jpeg'=>'image/jpeg',
'js'=>'application/x-javascript',
'midi'=>'audio/midi',
'mid'=>'audio/midi',
'mod'=>'audio/mod',
'mov'=>'movie/quicktime',
'mp3'=>'audio/mp3',
'mpg'=>'video/mpeg',
'mpeg'=>'video/mpeg',
'pdf'=>'application/pdf',
'png'=>'image/png',
'swf'=>'application/shockwave-flash',
'tif'=>'image/tiff',
'tiff'=>'image/tiff',
'wav'=>'audio/wav',
'xbm'=>'image/xbm',
'xml'=>'text/xml',
);
?>

rewrites

A la función rewrites se le proporciona un string como único parámetro y debe devolver unstringofalse.

Si se está utilizando fast-cgi o cgi, el parámetro pasado a la función es el valor de la variable$_SERVER['PATH_INFO']. De otro modo, el parámetro pasado a la función es el valor de la variable$_SERVER['REQUEST_URI'].

Si se devuelve un string, este se usa como la ruta de fichero interno. Si se devuelvefalse, webPhar() enviará un código de rechazo HTTP 403.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Lanza una excepción de tipoPharExceptioncuando no se puede abrir el fichero interno para salida, o si se llama desde un lugar que no sea una rutina de interoperabilidad. Si se pasa un array no válido amimetypeso se proporciona una llamada de retorno no válida arewrites, se lanza una excepción de tipoUnexpectedValueException.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::webPhar()

Con el ejemplo siguiente, el phar creado mostraráHola Mundosi uno explora/miphar.phar/index.phpo/miphar.phar, y mostrará la fuente deindex.phpssi uno explora/miphar.phar/index.phps.

<?php
// creating the phar archive:
try {
$phar= newPhar('miphar.phar');
$phar['index.php'] ='<?php echo "Hola Mundo"; ?>';
$phar['index.phps'] ='<?php echo "Hola Mundo"; ?>';
$phar->setStub('<?php
Phar::webPhar();
__HALT_COMPILER(); ?>'
);
} catch (
Exception $e) {
// manejar errores
}
?>

Ver también

  • Phar::mungServer()- Definir una lista de hasta 4 variables $_SERVER que debería ser modificadas para la ejecución
  • Phar::interceptFileFuncs()- Ordenar a phar interceptar fopen, file_get_contents, opendir, y todas las funciones relacionadas con estadísticas


Tabla de contenidos



La clase PharData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Introducción

La clase PharData proporciona una interfaz de alto nivel para el acceso y la creación de archivos tar y zip no ejecutables. Debido a que estos archivos no contienen una rutina de interoperabilidad y no pueden ser ejecutados por la extensión phar, es posible crear y manipular ficheros zip y tar normales con la clase PharData incluso si la opción del php.iniphar.readonlyestá establecida a1.

Sinopsis de la Clase

classPharDataextendsPhar{
/* Métodos */
addEmptyDir(string$dirname):bool
publicPhar::addFile(string$file,string$localname= ?):void
addFromString(string$localname,string$contents):bool
publicPhar::buildFromDirectory(string$base_dir,string$regex= ?):array
buildFromIterator(Iterator$iter,string$base_directory= ?):array
compress(int$compression,string$extension= ?):object
compressFiles(int$compression):bool
__construct(
    string$fname,
    int$flags= ?,
    string$alias= ?,
    int$format=Phar::TAR
)
convertToData(int$format= ?,int$compression= ?,string$extension= ?):PharData
convertToExecutable(int$format= ?,int$compression= ?,string$extension= ?):Phar
copy(string$oldfile,string$newfile):bool
decompress(string$extension= ?):object
delete(string$entry):bool
extractTo(string$pathto,string|array$files= ?,bool$overwrite= false):bool
isWritable():bool
offsetSet(string$offset,string$value):void
offsetUnset(string$offset):bool
setAlias(string$alias):bool
setDefaultStub(string$index= ?,string$webindex= ?):bool
publicPhar::setMetadata(mixed$metadata):void
publicPhar::setSignatureAlgorithm(int$sigtype):void
setStub(string$stub,int$len= -1):bool
/* Métodos heredados */
publicPhar::addEmptyDir(string$dirname):void
publicPhar::addFile(string$file,string$localname= ?):void
publicPhar::addFromString(string$localname,string$contents):void
finalpublicstaticPhar::apiVersion():string
publicPhar::buildFromDirectory(string$base_dir,string$regex= ?):array
publicPhar::buildFromIterator(Iterator$iter,string$base_directory= ?):array
finalpublicstaticPhar::canCompress(int$type= 0):bool
finalpublicstaticPhar::canWrite():bool
publicPhar::compress(int$compression,string$extension= ?):object
publicPhar::compressFiles(int$compression):void
publicPhar::__construct(string$fname,int$flags= ?,string$alias= ?)
publicPhar::convertToData(int$format= 9021976,int$compression= 9021976,string$extension= ?):PharData
publicPhar::convertToExecutable(int$format= 9021976,int$compression= 9021976,string$extension= ?):Phar
publicPhar::copy(string$oldfile,string$newfile):bool
publicPhar::count():int
finalpublicstaticPhar::createDefaultStub(string$indexfile= ?,string$webindexfile= ?):string
publicPhar::decompress(string$extension= ?):object
publicPhar::delMetadata():bool
publicPhar::delete(string$entry):bool
publicPhar::extractTo(string$pathto,string|array$files= ?,bool$overwrite= false):bool
publicPhar::getAlias():?string
publicPhar::getModified():bool
publicPhar::getPath():string
publicPhar::getSignature():array
publicPhar::getStub():string
finalpublicstaticPhar::getSupportedCompression():array
finalpublicstaticPhar::getSupportedSignatures():array
publicPhar::getVersion():string
publicPhar::hasMetadata():bool
finalpublicstaticPhar::interceptFileFuncs():void
publicPhar::isBuffering():bool
publicPhar::isFileFormat(int$format):bool
finalpublicstaticPhar::isValidPharFilename(string$filename,bool$executable= true):bool
publicPhar::isWritable():bool
finalpublicstaticPhar::loadPhar(string$filename,string$alias= ?):bool
finalpublicstaticPhar::mapPhar(string$alias= ?,int$dataoffset= 0):bool
finalpublicstaticPhar::mount(string$pharpath,string$externalpath):void
finalpublicstaticPhar::mungServer(array$munglist):void
publicPhar::offsetExists(string$offset):bool
publicPhar::offsetGet(string$offset):int
publicPhar::offsetSet(string$offset,string$value):void
publicPhar::offsetUnset(string$offset):bool
finalpublicstaticPhar::running(bool$retphar= true):string
publicPhar::setAlias(string$alias):bool
publicPhar::setDefaultStub(string$index= ?,string$webindex= ?):bool
publicPhar::setMetadata(mixed$metadata):void
publicPhar::setSignatureAlgorithm(int$sigtype,string$privatekey= ?):void
publicPhar::setStub(string$stub,int$len= -1):bool
publicPhar::stopBuffering():void
finalpublicstaticPhar::unlinkArchive(string$archive):bool
finalpublicstaticPhar::webPhar(
    string$alias= ?,
    string$index= "index.php",
    string$f404= ?,
    array$mimetypes= ?,
    callable$rewrites= ?
):void
}

PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addEmptyDirAñadir un directorio vacío al archivo tar/zip

Descripción

PharData::addEmptyDir(string$dirname):bool

Con este método se crea un directorio vacío con la ruta dada pordirname. Este método es similar aZipArchive::addEmptyDir().

Parámetros

dirname

El nombre de directorio vacío a crear en el archivo tar o zip

Valores devueltos

No devuelve ningún valor, se lanza una excepción en caso de error.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::addEmptyDir()

<?php
try {
$a= newPharData('/ruta/a/phar.phar');

$a->addEmptyDir('/ruta/completa/a/fichero');
// demuestra cómo se almacena este fichero
$b=$a['ruta/completa/a/fichero']->isDir();
} catch (
Exception $e) {
// manejar los errores aquí
}
?>

Ver también



PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFileAñadir un fichero desde el sistema de ficheros al archivo tar/zip

Descripción

publicPhar::addFile(string$file,string$localname= ?):void

Con este método, cualquier fichero o URL se puede añadir al arcivo tar/zip. Si se especifica el segundo parámetro opcionallocalname, el fichero será almacenado en el archivo con el nombre dado por el parámetro, si no se usará el parámetrofilecomo la ruta para almacentar dentro del archivo. Las URLs deben tener un nombre local o se lanzará una excepción. Este método es similar aZipArchive::addFile().

Parámetros

file

La ruta completa o relativa del fichero del disco a ser añadido al archivo phar.

localname

Ruta con la que el fichero será almacenado en el archivo.

Valores devueltos

No devuelve ningún valor, se lanza una excepción en caso de error.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::addFile()

<?php
try {
$a= newPharData('/ruta/a/phar.phar');

$a->addFile('/ruta/completa/a/fichero');
// demuestra cómo se almacena este fichero
$b=$a['ruta/completa/a/fichero']->getContent();

$a->addFile('/ruta/completa/a/fichero','mi/fichero.txt');
$c=$a['mi/fichero.txt']->getContent();

// demostrar el uso de una URL
$a->addFile('http://www.ejemplo.com','ejemplo.html');
} catch (
Exception $e) {
// manejar los errores aquí
}
?>

Ver también



PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFromStringAñadir un fichero desde el sistema de ficheros al archivo tar/zip

Descripción

PharData::addFromString(string$localname,string$contents):bool

Con este método, cuanquierl cadena se puede añadir al archivo tar/zip. El fichero será almacenado en el archivo conlocalnamecomo su ruta. Este método es similar aZipArchive::addFromString().

Parámetros

localname

Ruta con la que el fichero será almacenado en el archivo.

contents

El contenido del fichero a almacenar

Valores devueltos

No devuelve ningún valor, se lanza una excepción en caso de error.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::addFromString()

<?php
try {
$a= newPharData('/ruta/a/phar.phar');

$a->addFromString('ruta/a/fichero.txt','mi sencillo fichero');
$b=$a['ruta/a/fichero.txt']->getContent();

// para añadir contenido desde un gestor de flujos para ficheros grandes, use offsetSet()
$c=fopen('/ruta/a/fichero_enorme.bin');
$a['fichero_grande.bin'] =$c;
fclose($c);
} catch (
Exception $e) {
// manejar los errores aquí
}
?>

Ver también



PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromDirectoryConstruir un archivo tar/zip desde los ficheros de un directorio

Descripción

publicPhar::buildFromDirectory(string$base_dir,string$regex= ?):array

Rellena un archivo phar con el contenido de un directorio. El segundo parámtro opcional es una expresión regular (pcre) que se utiliza para excluir ficheros. Cualquier nombre de fichero que coincida con la expresión regular será incluido, todos los demás serán excluidos. Para un control más exhaustivo, usePharData::buildFromIterator().

Parámetros

base_dir

La ruta completa o relativa al directorio que contiene todos los ficheros a añadir al archivo.

regex

Una expresión regular de pcre opcional que se usa para filtrar la lista de ficheros. Solamente las rutas de fichero que coincidan con la expresión regular serán incluidas en el archivo.

Valores devueltos

Phar::buildFromDirectory()devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.

Errores/Excepciones

Este método lanza una excepción de tipoBadMethodCallExceptioncuando no puede instanciar los iteradores intermos del directorio, o una excepción de tipoPharExceptionsi hubo errores al guardar el archivo phar.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::buildFromDirectory()

<?php
$phar
= newPharData('proyecto.tar');
// añadir todos los ficheros del proyecto
$phar->buildFromDirectory(dirname(__FILE__) .'/proyecto');

$phar2= newPharData('proyecto2.zip');
// añadir todos los ficheros del, incluir solamente los ficheros php
$phar2->buildFromDirectory(dirname(__FILE__) .'/proyecto','/\.php$/');
?>

Ver también



PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromIteratorConstruir un archivo tar o zip desde un iterador

Descripción

PharData::buildFromIterator(Iterator$iter,string$base_directory= ?):array

Rellena un archivo tar o zip desde un iterador. Están soportados dos estilos de iteradores, los iteradores que mapean el nombre de fichero dentro del tar/zip al nombre del fichero en disco, y los iteradores como DirectoryIterator que devuelven objetos de la clase SplFileInfo. Se requiere el segundo parámetro para los iteradores que devuelven objetos de la clase SplFileInfo.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::buildFromIterator()con SplFileInfo

Para la mayoría de los archivos tar/zip, el archivo reflejará la distribución real de directorios, y el segundo estilo es el más útil. Por ejemplo, para crear un archivo tar/zip que contenga los ficheros n esta distribución de muestra de directorios:

/ruta/al/proyecto/
                 config/
                        dist.xml
                        debug.xml
                 lib/
                     fichero1.php
                     fichero2.php
                 src/
                     procesa_algo.php
                 www/
                     index.php
                 cli/
                     index.php

Este código podría usarse para añadir estos ficheros al archivo tar "proyecto.tar":

<?php
$phar
= newPharData('proyecto.tar');
$phar->buildFromIterator(
new
RecursiveIteratorIterator(
new
RecursiveDirectoryIterator('/ruta/al/proyecto')),
'/ruta/al/proyecto');
?>

El ficheroproject.tarse puede usar inmediatamente.PharData::buildFromIterator()no establece valores como la compresión y metainformación, que se puede hacer después de crear el archivo tar/zip.

Como observación interesante,PharData::buildFromIterator()también se puede usar para copiar el contenido de un archivo phar, tar o zip existentese, ya que los objetos de la clase PharData descienden de la claseDirectoryIterator:

<?php
$phar
= newPharData('proyecto.tar');
$phar->buildFromIterator(
new
RecursiveIteratorIterator(
new
Phar('/ruta/a/otro_phar.phar')),
'phar:///ruta/a/otro_phar.phar/ruta/al/proyecto');
$phar->setStub($phar->createDefaultStub('cli/index.php','www/index.php'));
?>

Ejemplo #2 Un ejemplo dePharData::buildFromIterator()con otros iteradores

La segunda forma de iterador se puede usar con cualquier iterador que devuelva un mapeo clave => valor, tal como un objeto de la claseArrayIterator:

<?php
$phar
= newPharData('proyecto.tar');
$phar->buildFromIterator(
new
ArrayIterator(
array(
'fichero/interno.php'=>dirname(__FILE__) .'/algun_fichero.php',
'otro/fichero.jpg'=>fopen('/rota/a/archivo_grande.jpg','rb'),
)));
?>

Parámetros

iter

Cualquier iterador que mapee de forma asociativa el fichero tar/zip a la ubiciación o que devuelva objetos de la clase SplFileInfo

base_directory

Para los iteradores que devuelven objetos de la clase SplFileInfo, es la porción de cada ruta completa de fichero a eliminar cuando de añada al archivo tar/zip

Valores devueltos

PharData::buildFromIterator()devuelve un array asociativo que que mapea la ruta interna del fichero a la ruta completa del mismo en el sistema de ficheros.

Errores/Excepciones

Este método lanza una excepción de tipoUnexpectedValueExceptioncuando el iterador devuelve valores incorrectos, tales como una clave de tipo integer en lugar de una cadena, una excepción de tipoBadMethodCallExceptioncuando se pasa un iterador basado en SplFileInfo sin un parámetrobase_directory, o una excepción de tipoPharExceptionsi hubo errores al guardar el archivo phar.

Ver también



PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressComprimir el archivo tar/zip entero usando la compresión Gzip o Bzip2

Descripción

PharData::compress(int$compression,string$extension= ?):object

Para archivos tar, este método comprime el archivo entero usando la compresión gzip o bzip2. El fichero resultante puede ser procesado con el comando gunzip/bunzip, o se puede acceder a él directa y transparentemente con la extensión Phar.

Para archivos phar basados en Zip, este método falla con el lanzamiento de una excepción. La extensiónzlibdebe estar habilitada para poder comprimir con la compresión gzip, y la extensiónbzip2debe estar habilitada para poder comprimir con la compresión bzip2.

Además, este método renombra automáticamente el archivo, añadiéndole.gz,.bz2o eliminado la extensión si se pasaPhar::NONEpara eliminar la compresión. De forma alternativa, se puede expecificar una extensión de fichero con el segundo parámetro.

Parámetros

compression

La compresión debe serPhar::GZoPhar::BZ2para añadir compresión, oPhar::NONEpara eliminarla.

extension

Por omisión, la extensión es.tar.gzo.tar.bz2para comprimir un tar, y.tarpara descomprimirlo.

Valores devueltos

Devuelve un objeto de la clasePharData.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la extensiónzlibno está disponible, o la extensiónbzip2no está habilitada.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::compress()

<?php
$p
= newPharData('/ruta/a/mi.tar');
$p['myfile.txt'] ='hi';
$p['myfile2.txt'] ='hi';
$p1=$p->compress(Phar::GZ);// copia a /ruta/a/mi.tar.gz
$p2=$p->compress(Phar::BZ2);// copia a /ruta/a/mi.tar.bz2
$p3=$p2->compress(Phar::NONE);// excepción: /ruta/a/mi.tar ya existe
?>

Ver también

  • Phar::compress()- Comprimir el archivo Phar entero usando la compresión Gzip o Bzip2



PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressFilesComprime todos los ficheros del archivo tar/zip actual

Descripción

PharData::compressFiles(int$compression):bool

Para archivos phar basados en tar, este método lanza una excepción de tipoBadMethodCallException, ya que la compresión de ficheros individuales dentro de un archivo tar no está soportada por el formato de fichero. UsePhar::compress()para comprimir un archivo phar entero basado en tar.

Para achivos basados en Zip, este método comprime todos los ficheros del archivo usando la compresión especificada. Las extensioneszlibobzip2deben estar habilitadas para aprovechar esta característica. Además, si cualquier fichero ya está comprimido con la compresión bzip2/zlib, la extensión respectiva debe estar habilitada para poder descomprimir los ficheros antes de re-comprimirlos.

Parámetros

compression

La compresión debe serPhar::GZoPhar::BZ2para añadir compresión, oPhar::NONEpara eliminarla.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónzlibno está disponible, o si cualquier fichero está comprimido con la compresión bzip2 y la extensiónbzip2no está habilitada.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::compressFiles()

<?php
$p
= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
foreach (
$pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach (
$pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
?>

El resultado del ejemplo sería:

string(13) "mifichero.txt"
bool(false)
bool(false)
bool(false)
string(14) "mifichero2.txt"
bool(false)
bool(false)
bool(false)
string(13) "mifichero.txt"
int(4096)
bool(false)
bool(true)
string(14) "mifichero2.txt"
int(4096)
bool(false)
bool(true)

Ver también



PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__constructConstruir un objeto de archivo tar o zip no ejecutable

Descripción

PharData::__construct(
    string$fname,
    int$flags= ?,
    string$alias= ?,
    int$format=Phar::TAR
)

Parámetros

fname

Ruta a un archivo tar/zip existente o para ser creado

flags

Banderas a pasar a la clase padreRecursiveDirectoryIterator.

alias

Alias con el que referirse al archivo Phar en las llamadas a funcionalidades de flujos.

format

Una de lasconstantes de formato de ficherodisponiblies dentro de la clasePhar.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi se llama dos veces, o una excepción de tipoUnexpectedValueExceptionsi no se puede abrir el archivo phar.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::__construct()

<?php
try {
$p= newPharData('/ruta/a/mi.tar',Phar::CURRENT_AS_FILEINFO|Phar::KEY_AS_FILENAME);
} catch (
UnexpectedValueException $e) {
die(
'No se pudo abrir mi.tar');
} catch (
BadMethodCallException $e) {
echo
'Técnicamente esto no puede suceder';
}
echo
file_get_contents('phar:///ruta/a/mi.tar/ejemplo.txt');
?>



PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToDataConvertir un archivo phar en un fichero tar o zip no ejecutable

Descripción

PharData::convertToData(int$format= ?,int$compression= ?,string$extension= ?):PharData

Este método se usa para convertir un archivo tar o zip no ejecutable a otro formato no ejecutable.

Si no se especifica ningún cambio, este método lanza una excepción de tipoBadMethodCallExceptionEste método debería usarse para convertir un archivo tar a formato zip o viceversa. Aunque es posible cambiar la compresión de un archivo tar simplemente usando este método, es mejor utilizad el métodoPharData::compress()para una consistencia lógica.

En caso de éxito, el metodo crea un nuevo archivo en disco y devuelve un objeto de la clasePharData. El archivo antiguo no se elimina del disco, y debería hacerse manualmente después de que el proceso haya finalizado.

Parámetros

format

Este parámetro debería serPhar::TARoPhar::ZIP. Si se establece anull, se conservará el formato de fichero existente.

compression

Este parámetro debería serPhar::NONEpara no comprimir el archivo completo,Phar::GZpara la compresión basada en zlib, yPhar::BZ2para la compresión basada en bzip.

extension

Este parámetro se utiliza para sobrescribir la extensión de fichero predeterminada de un archivo convertido. Observe que.pharno puede ser usado en ningún lugar del nombre de fichero de un archivo tar o zip no ejecutable.

Si se convierte a un archivo basado en tar, las extensiones predeterminadas son.tar,.tar.gz, y.tar.bz2dependiendo de la compresión especificada. Para archivos basados en zip, la extensión predetermianda es.zip.

Valores devueltos

El método devuelve un objetoPharDataen caso de éxito, y lanza una excepción en caso de error.

Errores/Excepciones

Este método lanza una excepción de tipoBadMethodCallExceptioncuando no se puede comprimir, se ha especificado un método de compresión desconocido, el archivo solicitado está almacenado en buffer conPhar::startBuffering()y no se ha cerrado conPhar::stopBuffering(), y una excepción de tipoPharExceptionsi se encontró algún problema durante el proceso de la creación de phar.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::convertToData()

Utilizar PharData::convertToData():

<?php
try {
$tarphar= newPharData('miphar.tar');
// observe que miphar.phar.tar *no* está desvinculado.
// convertirlo a un formato de fichero tar no ejecutable,
// se crea miphar.zip
$zip=$tarphar->convertToData(Phar::ZIP);
// crear miphar.tbz
$tgz=$tarphar->convertToData(Phar::TAR,Phar::BZ2,'.tbz');
// crear miphar.phar.tgz
$phar=$tarphar->convertToData(Phar::PHAR);// lanza una excepción
} catch (Exception $e) {
// manejar el error aquí
}
?>

Ver también



PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToExecutableConvertir un archivo tar/zip no ejecutable en un archivo phar ejecutable

Descripción

PharData::convertToExecutable(int$format= ?,int$compression= ?,string$extension= ?):Phar

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Este método se utiliza para convertir un arhivo tar o zip no ejecutable en un archivo phar ejecutable. Se puede usar cualquiera de los tres formatos de fichero (phar, tar o zip), y también se puede realizar la compresión del archivo completo.

Si no se especifica ningún cambio, este método lanza una excepción de tipoBadMethodCallException

En caso de éxito, el metodo crea un nuevo archivo en disco y devuelve un objeto de la clasePharData. El archivo antiguo no se elimina del disco, y debería hacerse manualmente después de que el proceso haya finalizado. If successful, the method creates a new archive on disk and returns aPharobject. The old archive is not removed from disk, and should be done manually after the process has finished.

Parámetros

format

Este parámetro debería serPhar::PHAR,Phar::TAR, oPhar::ZIP. Si se establece anull, se conservará el formato de fichero existente.

compression

Este parámetro debería serPhar::NONEpara no comprimir el archivo completo,Phar::GZpara la compresión basada en zlib, yPhar::BZ2para la compresión basada en bzip.

extension

Este parámetro se utiliza para sobrescribir la extensión de fichero predeterminada de un archivo convertido. Observe que todos los archivos phar basados en zip o en tar deben contener.pharen su extensión de fichero para poder ser procesados como un archivo phar.

Si se convierte a un archivo basado en phar, las extensiones predeterminadas son.phar,.phar.gz, o.phar.bz2dependiendo de la compresión especificada. Para archivos phar basados en tar, las extensiones predeterminadas son.phar.tar,.phar.tar.gz, y.phar.tar.bz2. Para archivos phar basados en zip, la estensión predeterminada es.phar.zip.

Valores devueltos

El método devuelve un objetoPharen caso de éxito, y lanza una excepción en caso de error.

Errores/Excepciones

Este método lanza una excepción de tipoBadMethodCallExceptioncuando no se puede comprimir, se ha especificado un método de compresión desconocido, el archivo solicitado está almacenado en buffer conPhar::startBuffering()y no se ha cerrado conPhar::stopBuffering(), una excepción de tipoUnexpectedValueExceptionsi el soporte para escritura está deshabilitado, y una excepción de tipoPharExceptionsi se encontró algún problema durante el proceso de la creación de phar.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::convertToExecutable()

Utilizar PharData::convertToExecutable():

<?php
try {
$tarphar= newPharData('miphar.tar');
// convertirlo al formato de fichero phar
// observe que miphar.tar *no* está desvinculado
$phar=$tarphar->convertToExecutable(Phar::PHAR);// crea miphar.phar
$phar->setStub($phar->createDefaultStub('cli.php','web/index.php'));
// crea miphar.phar.tgz
$comprimido=$tarphar->convertToExecutable(Phar::TAR,Phar::GZ,'.phar.tgz');
} catch (
Exception $e) {
// manejar el error aquí
}
?>

Ver también



PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::copyCopiar un fichero interno de un archivo phar a otro fichero nuevo dentro del phar

Descripción

PharData::copy(string$oldfile,string$newfile):bool

Copia un fichero interno de un archivo tar/zip a otro fichero nuevo dentro del mismo archivo. Esta es una alternativa orientada a objetos para usarcopy()con la envoltura de flujos phar.

Parámetros

oldfile

newfile

Valores devueltos

Devuelvetrueen caso de éxito, pero es más seguro encerrar la llamada al método en un bloque try/catch y asumir el éxito si no se lanza ninguna excepción.

Errores/Excepciones

Lanza una excepción de tipoUnexpectedValueExceptionsi el fichero origen no exite, el fichero destino ya existe, el acceso a escritura está deshabilitado, la apertura de cualquiera de los dos ficheros falla, la lectura del fichero fuente falla, o una excepción de tipoPharExceptionsi la escritura de los cambios del phar falla.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::copy()

Este ejemplo muestra el uso dePharData::copy()y su equivalente con envoltura de flujos. La principal diferencia entre los dos enfoques es el manejo de errores. Todos los métodos de PharData lanzan excepciones, mientras que la envoltura de flujos utilizatrigger_error().

<?php
try {
$phar= newPharData('miphar.tar');
$phar['a'] ='hola';
$phar->copy('a','b');
echo
$phar['b'];// imprime "phar://miphar.tar/b"
} catch (Exception $e) {
// manejar errores
}

// el equivalente con envoltura de flujos del código de arriba.
// Se dispara E_WARNINGS en caso de error en vez de excepciones.
copy('phar://miphar.tar/a','phar//miphar.tar/c');
echo
file_get_contents('phar://miphar.tar/c');// imprime "hola"
?>



PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressDescomprimir un archivo Phar entero

Descripción

PharData::decompress(string$extension= ?):object

Para archivos phar basados en tar, este método descomprime el archivo entero.

Para archivos phar basados en Zip, este método este método falla con el lanzamiento de una excepción. La extensiónzlibdebe estar habilitada para descomprimir un archivo comprimido con la compresión gzip, y la extensiónbzip2debe estar habilitada para descomprimir un archivo comprimido con la compresión bzip2.

Además, este método renombra automáticamente la extensión de fichero del archivo,.tarpor omisión. De forma alternativa, se puede expecificar una extensión de fichero con el segundo parámetro.

Parámetros

extension

Para la descompresión, las extensión de fichero predeterminada es.phar.tar. Use este parámetro para especificar otra extensión de fichero. Observe que todos los archivos no ejecutables no pueden contener.pharen su nombre de fichero.

Valores devueltos

Devuelve un objeto de la clasePharData.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la extensiónzlibno está disponible, o la extensiónbzip2no está habilitada.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::decompress()

<?php
$p
= newPharData('/ruta/a/mi.tar.gz');
$p->decompress();// crea /ruta/a/mi.tar
?>

Ver también



PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressFilesDescomprimir todos los ficheros del archivo zip actual

Descripción

PharData::decompressFiles():bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Para archivos basados en tar, este método lanza una excepción de tipoBadMethodCallException, ya que la compresión de ficheros individuales dentro de un archivo tar no está soportada por el formato de fichero. UsePhar::compress()para comprimir un archivo phar entero basado en tar.

Para achivos phar basados en Zip y phar, este método descomprime todos los ficheros del archivo. Las extensioneszlibobzip2deben estar habilitadas para aprvechar esta característica si cualquier fichero está comprimido con la compresión bzip2/zlib.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la extensiónzlibno está disponible, o si cualquier fichero está comprimido con la compresión bzip2 y la extensiónbzip2no está habilitada. ThrowsBadMethodCallExceptionif thezlibextension is not available, or if any files are compressed using bzip2 compression and thebzip2extension is not enabled.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::decompressFiles()

<?php
$p
= newPharData('/ruta/a/mi.zip');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
$p->compressFiles(Phar::GZ);
foreach (
$pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach (
$pas$fichero) {
var_dump($fichero->getFileName());
var_dump($fichero->isCompressed());
var_dump($fichero->isCompressed(Phar::BZ2));
var_dump($fichero->isCompressed(Phar::GZ));
}
?>

El resultado del ejemplo sería:

string(13) "mifichero.txt"
int(4096)
bool(false)
bool(true)
string(14) "mifichero2.txt"
int(4096)
bool(false)
bool(true)
string(13) "mifichero.txt"
bool(false)
bool(false)
bool(false)
string(14) "mifichero2.txt"
bool(false)
bool(false)
bool(false)

Ver también



PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delMetadataEliminar la metainformación global de un archivo zip

Descripción

PharData::delMetadata():bool

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Elimina la metainformación global de un archivo zip

Parámetros

Valores devueltos

Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::delMetaData()

<?php
try {
$phar= newPharData('miphar.zip');
var_dump($phar->getMetadata());
$phar->setMetadata("hola, qué tal");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (
Exception $e) {
// manejar errores
}
?>

El resultado del ejemplo sería:

NULL
string(14) "hola, qué tal"
NULL

Ver también



PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::deleteBorrar un fichero dentro de un archivo tar/zip

Descripción

PharData::delete(string$entry):bool

Borra un fichero dentro de un archivo. Esto es el equivalente funcional de llamar aunlink()en el equivalente de envoltura de flujos, tal como se muestra en el ejemplo de abajo.

Parámetros

entry

La ruta dentro de un archivo para borrar el fichero.

Valores devueltos

Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi se produjo algún error al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::delete()

<?php
try {
$phar= newPharData('miphar.zip');
$phar->delete('desvincular/yo.php');
// esto es equivalente a:
unlink('phar://miphar.phar/desvincular/yo.php');
} catch (
Exception $e) {
// manejar errores
}
?>

Ver también



PharData::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__destructDestructs a non-executable tar or zip archive object

Descripción

publicPharData::__destruct()

Parámetros

Esta función no tiene parámetros.



PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::extractToExtraer el contenido de un archivo tar/zip a un directorio

Descripción

PharData::extractTo(string$pathto,string|array$files= ?,bool$overwrite= false):bool

Extrae todos los ficheros de un archivo tar/zip al disco. Los ficheros y directorios extraídos conservan los mismos permisos que los almacenados en el archivo. Los parámetros opcionales permiten controlar qué ficheros serán extraídos, y si los ficheros existentes en disco podrán ser sobrescritos. El segundo parámetrofilespuede ser el nombre de un fichero o directorio a extraer, o un array de nombre de ficheros y directorios a extraer. Por omisión, este método no sobrescribirá los ficheros existentes, aunque el tercer parámetro se puede establecer a true para habilitar la sobrescritura de ficheros. Este método es similar aZipArchive::extractTo().

Parámetros

pathto

Ruta donde extraer los ficheros dados porfiles

files

El nombre de un fichero o directorio a extraer, o un array de ficheros/directorios a extraer.

overwrite

Esteblecer atruepara habilitar la sobrescritura de ficheros existentes

Valores devueltos

Devuelvetrueen caso de éxito, pero es mejor comprobar si lanza alguna excepción, y asumir el éxito si no se lanza ninguna.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::extractTo()

<?php
try {
$phar= newPharData('miphar.tar');
$phar->extractTo('/ruta/completa');// extraer todos los ficheros
$phar->extractTo('/otra/ruta','fichero.txt');// extraer solamente fichero.txt
$phar->extractTo('/esta/ruta',
array(
'fichero1.txt','fichero2.txt'));// extraer solamente 2 ficheros
$phar->extractTo('/tercera/ruta',null,true);// extraer todos los ficheros y sobrescribirlos
} catch (Exception $e) {
// manejar errores
}
?>

Ver también



PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::isWritableDevolver si el archivo tar/zip se puede modificar

Descripción

PharData::isWritable():bool

Este método devuelvetruesi el archivo tar/zip archive del disco no es de sólo lectura. A diferencia dePhar::isWritable(), los archivos tar/zip de sólo datos se pueden modificar incluso siphar.readonlyestá establecido a1.

Parámetros

No tiene parámetros.

Valores devueltos

Devuelvetruesi el archivo tar/zip puede ser modificado

Ver también



PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetSetEstablecer el contenido de un fichero dentro de un tar/zip a aquel de un fichero o cadena externos

Descripción

PharData::offsetSet(string$offset,string$value):void

Ésta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo tar/zip utilizando los corchetes de acceso al array. offsetSet se utiliza para modificar un fichero existente, o añadir un nuevo fichero al archivo tar/zip.

Parámetros

offset

El nombre del fichero (ruta relativa) a modificar en un archivo tar o zip.

value

El contenido del fichero.

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Lanza un excepción de tipoPharExceptionsi existe cualquier problema volcando los cambios hechos al archivo tar/zip al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::offsetSet()

No se debería acceder directamente a offsetSet, en su lugar se utiliza el operador[]para acceder al array.

<?php
$p
= newPharData('/ruta/a/mi.phar',0,'mi.phar');
try {
// llama a offsetSet
$p['fichero.txt'] ='Hola qué tal';
} catch (
Exception $e) {
echo
'No se pudo modificar fichero.txt:',$e;
}
?>

Ver también

  • Phar::offsetSet()- Establecer el contenido de un fichero interno a aquel de un fichero externo



PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetUnsetEliminar un ficerho de un archivo tar/zip

Descripción

PharData::offsetUnset(string$offset):bool

Ésta es una implementación de la interfazArrayAccessque permite la manipulación directa del contenido de un archivo tar/zip utilizando los corchetes de acceso al array. offsetUnset se utiliza para borrar un fichero existente, y es llamado por el constructor de lenguajeunset().

Parámetros

offset

El nombre del fichero (ruta relativa) a eliminar en un archivo tar o zip.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza un excepción de tipoPharExceptionsi existe cualquier problema volcando los cambios hechos al archivo tar/zip al disco.

Ejemplos

Ejemplo #1 Un ejemplo dePharData::offsetUnset()

<?php
$p
= newPharData('/ruta/a/mi.phar',0,'mi.phar');
try {
// borra fichero.txt de mi.phar llamando a offsetUnset
unset($p['fichero.txt']);
} catch (
Exception $e) {
echo
'No se pudo borrar fichero.txt: ',$e;
}
?>

Ver también



PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setAliasfunción sin sentido (Phar::setAlias no es válido para PharData)

Descripción

PharData::setAlias(string$alias):bool

Los archivos tar/zip no ejecutables no pueden tener un alias, por lo que este método simplemente lanza una excepción.

Parámetros

alias

Una cadena abreviada para referirse a este archivo en el acceso con la envoltura de flujophar. Este parámetro es ignorado.

Valores devueltos

Errores/Excepciones

Lanza una excepción de tipoPharExceptionen todas las llamdas al método

Ver también



PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setDefaultStubfunción sin sentido (Phar::setStub no es válido para PharData)

Descripción

PharData::setDefaultStub(string$index= ?,string$webindex= ?):bool

Los archivos tar/zip no ejecutables no pueden tener una rutina de interoperabilidad, por lo que este método simplemente lanza una excepción.

Parámetros

index

La ruta relativa dentro del archivo phar a ejectuar si se accede desde la línea de comandos

webindex

La ruta relativa dentro del archivo phar a ejectuar si se accede desde un servidor web

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionen todas las llamadas al método

Ver también

  • Phar::setDefaultStub()- Establecer el cargador o la rutina de interoperabilidad de un archivo Phar al cargador predeterminado



Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadataEstablecer la metainformación de un archivo phar

Descripción

publicPhar::setMetadata(mixed$metadata):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Phar::setMetadata()debería usarse para almacenar información personalizada que describa algo sobre el archivo phar como una entidad completa.PharFileInfo::setMetadata()debería usarse para metainformación específica de cada fichero. La metainformación puede ralentizar la velocidad de carga de un archivo phar si la información es grande.

Algunos posibles usos para la metainformación incluyen especificar qué fichero dentro del archivo debería usarse para cargar el archivo, o la ubicación de un fichero de manifiesto como el fichero package.xml de» PEAR. Sin embargo, se puede almacenar cualquier información útil que describa el archivo phar.

Parámetros

metadata

Cualquier variable de PHP que contenga la información a almacenar que describa el archivo phar

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Un ejemplo dePhar::setMetadata()

<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.php'] ='<?php echo "hola"';
$p->setMetadata(array('bootstrap'=>'fichero.php'));
var_dump($p->getMetadata());
} catch (
Exception $e) {
echo
'No se pudo crear y/o modificar el phar:',$e;
}
?>

El resultado del ejemplo sería:

array(1) {
  ["bootstrap"]=>
  string(11) "fichero.php"
}

Ver también



Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithmEstablecer el algoritmo de firma para un phar y aplicarlo

Descripción

publicPhar::setSignatureAlgorithm(int$sigtype):void

Nota:

Este método requiere que la opción dephp.iniphar.readonlyesté establecida a0para que trabaje con objetosPhar. De otra manera, se lanzará una excepción de tipoPharException.

Establece el algoritmo de firma para un phar y lo aplica. El algoritmo de firma debe ser una de las constantesPhar::MD5,Phar::SHA1,Phar::SHA256,Phar::SHA512, oPhar::OPENSSL. (PGP aún no está soportado y se recurre a SHA-1).

Parámetros

sigtype

Una de las constantesPhar::MD5,Phar::SHA1,Phar::SHA256,Phar::SHA512, orPhar::PGP

Valores devueltos

No devuelve ningún valor.

Errores/Excepciones

Lanza una excepción de tipoUnexpectedValueExceptionpara muchos errores, una excepción de tipoBadMethodCallExceptionsi se llamó para un archivo basao en zip o en tar, y una excepción de tipoPharExceptionsi ocurrió algún problema al volcar los cambios al disco.

Ver también



PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setStubfunción sin sentido (Phar::setStub no es válido para PharData)

Descripción

PharData::setStub(string$stub,int$len= -1):bool

Los archivos tar/zip no ejecutables no pueden tener una rutina de interoperabilidad, por lo que este método simplemente lanza una excepción.

Parámetros

stub

Una cadena o un gestor de flujo abierto para usarlo como la rutina de interoperabilidad ejecutable de este archivo phar. Este parámetro es ignorado.

len

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionen todas las llamadas al método

Historial de cambios

VersiónDescripción
5.4.0Se añadió el parámetrolen.

Ver también

  • Phar::setStub()- Establecer el cargador de PHP o la rutina de interoperabilidad de un archivo Phar


Tabla de contenidos



La clase PharFileInfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Introducción

La clase PharFileInfo proporciona una interfaz de alto nivel para el contenido y los atributos de un único fichero dentro de un archivo phar.

Sinopsis de la Clase

classPharFileInfoextendsSplFileInfo{
/* Métodos */
publicchmod(int$permissions):void
publiccompress(int$compression):bool
public__construct(string$entry)
publicdecompress():bool
publicdelMetadata():bool
publicgetCRC32():int
publicgetCompressedSize():int
publicgetContent():string
publicgetPharFlags():int
publichasMetadata():bool
publicisCRCChecked():bool
publicisCompressed(int$compression_type= 9021976):bool
publicsetMetadata(mixed$metadata):void
}

PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::chmodEsteblecer los bits de permiso específicos del fichero

Descripción

publicPharFileInfo::chmod(int$permissions):void

PharFileInfo::chmod()permite el ajuste del bit de permiso ejecutable de un fichero, así como el bit de sólo lectura. El bit de escritura se ignora, y se establece en tiempo de ejecución basándose en la variable INIphar.readonly. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.

Parámetros

permissions

Los permisos (véasechmod())

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::chmod()

<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar('nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.sh'] ='#!/usr/local/lib/php
<?php echo "hi"; ?>'
;
// establecer el bit ejecutable
$p['fichero.sh']->chmod(0555);
var_dump($p['fichero.sh']->isExecutable());
} catch (
Exception $e) {
echo
'No se pudo crear/modificar el phar: ',$e;
}
?>

El resultado del ejemplo sería:

bool(true)



PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::compressComprimir la entrada del Phar actual con la compresión zlib o bzip2

Descripción

publicPharFileInfo::compress(int$compression):bool

Este método comprime el fichero dentro de un archivo Phar usando la compresión bzip2 o zlib. Las extensionesbzip2ozlibdeben estar habilitadas para aprovechar esta característica. Además, si el fichero ya está comprimido, la extensión respectiva debe estar habilitada para poder descomprimir el fichero. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónbzip2/zlibno está disponible.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::compress()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
var_dump($fichero->isCompressed(Phar::BZ2));
$p['mifichero.txt']->compress(Phar::BZ2);
var_dump($fichero->isCompressed(Phar::BZ2));
} catch (
Exception $e) {
echo
'Falló la operación de crear/modificar mi.phar: ',$e;
}
?>

El resultado del ejemplo sería:

bool(false)
bool(true)

Ver también



PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__constructConstruir un objeto de entrada Phar

Descripción

publicPharFileInfo::__construct(string$entry)

Este método no debería llamarse directamente. En su lugar, un objeto de la clase PharFileInfo se inicializa al llamar aPhar::offsetGet()a traves del acceso a un array.

Parámetros

entry

La URL completa para recuperar un fichero. Si se desea recuperar la informacion del fichoermi/fichero.phpdesde el pharboo.phar, la entrada debería serphar://boo.phar/mi/fichero.php.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi__construct()es llamado dos veces. Lanza una excepción de tipoUnexpectedValueExceptionsi la URL del phar solicitado está malformada, el phar solicitado no se puede abrir, o el fichero no se puede encontrar dentro del phar.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::__construct()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['fichero_prueba.txt'] ="hola\nqué tal\namigo";
$fichero=$p['fichero_prueba.txt'];
foreach (
$ficheroas$línea=>$texto) {
echo
"línea número$línea:$texto";
}
// esto también funciona
$fichero= newPharFileInfo('phar:///ruta/a/mi.phar/fichero_prueba.txt');
foreach (
$ficheroas$línea=>$texto) {
echo
"línea número$línea:$texto";
}
} catch (
Exception $e) {
echo
'Las operaciones Phar fallaron: ',$e;
}
?>

El resultado del ejemplo sería:

línea número 1: hola
línea número 2: qué tal
línea número 3: amigo
línea número 1: hola
línea número 2: qué tal
línea número 3: amigo



PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::decompressDescomprimir la entrada Phar actual dentro del phar

Descripción

publicPharFileInfo::decompress():bool

Este método descompribe el fichero dentro de un archivo Phar. Dependiendo de cómo esté comprimido el fichero, las extensionesbzip2ozlibdeben estar habilitadas para aprovechar esta característica. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi la variable INIphar.readonlyestá activada, la extensiónbzip2/zlibno está disponible.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::decompress()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
$fichero->compress(Phar::GZ);
var_dump($fichero->isCompressed());
$p['mifichero.txt']->decompress();
var_dump($fichero->isCompressed());
} catch (
Exception $e) {
echo
'La operación de crear/modificar mi.phar falló: ',$e;
}
?>

El resultado del ejemplo sería:

int(4096)
bool(false)

Ver también



PharFileInfo::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::delMetadataEliminar la metainformación de una entrada

Descripción

publicPharFileInfo::delMetadata():bool

Eliminar la metainformación de una entrada, si existe.

Parámetros

No parameters.

Valores devueltos

Devuelvetrueen caso de éxito,falsesi la entrada no tiene metainformación. Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.

Errores/Excepciones

Lanza una excepción de tipoPharExceptionsi ocurrió algún error al volcar los cambios al disco, y una excepción de tipoBadMethodCallExceptionsi el acceso a escritura está deshabilitado.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::delMetaData()

<?php
try {
$a= newPhar('miphar.phar');
$a['hola'] ='hola';
var_dump($a['hola']->delMetadata());
$a['hola']->setMetadata('qué tal');
var_dump($a['hola']->delMetadata());
var_dump($a['hola']->delMetadata());
} catch (
Exception $e) {
// manejar errores
}
?>

El resultado del ejemplo sería:

bool(false)
bool(true)
bool(false)

Ver también



PharFileInfo::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__destructDestructs a Phar entry object

Descripción

publicPharFileInfo::__destruct()

Parámetros

Esta función no tiene parámetros.



PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCRC32Devolver el códido CRC32 o lanzar una exepción si la CRC no ha sido verificado

Descripción

publicPharFileInfo::getCRC32():int

Este método devuelve la suma de verificacióncrc32()del fichero dentro de un archivo Phar.

Valores devueltos

La suma de verificaicóncrc32()de un fichero dentro de un archivo Phar.

Errores/Excepciones

Lanza una excepción de tipoBadMethodCallExceptionsi el fichero no tiene aún su CRC32 verificado. Esto sería imposible con un uso normal, ya que la CRC es verificada al abrir el fichero para lectura o escritura.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::getCRC32()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
echo
$fichero->getCRC32();
} catch (
Exception $e) {
echo
'Las operaciones de escritura sobre mi.phar.phar fallaron: ',$e;
}
?>

El resultado del ejemplo sería:

1872820616



PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSizeDevolver el tamaño real de un fichero (con compresión) dentro de un archivo Phar

Descripción

publicPharFileInfo::getCompressedSize():int

Devuelve el tamaño del fichero dentro del archivo Phar. Los ficheros no comprimidos devolverán el mismo valor que si se utilizarafilesize()en vez defilesize()

Valores devueltos

El tamaño en bytes del fichero dentro del archivo Phar en disco.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::getCompressedSize()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
echo
$fichero->getCompressedSize();
} catch (
Exception $e) {
echo
'Las operaciones de escritura sobre mi.phar fallaron: ',$e;
}
?>

El resultado del ejemplo sería:

2

Ver también



PharFileInfo::getContent

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PharFileInfo::getContentGet the complete file contents of the entry

Descripción

publicPharFileInfo::getContent():string

This function behaves likefile_get_contents()but for Phar.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returns the file contents.



PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getMetadataDevolver la metainformación específica de un fichero almacenada con un fichero

Descripción

publicPharFileInfo::getMetadata():mixed

Devuelve la metainformación que fue almacenada en el manifiesto del archivo Phar para este fichero.

Parámetros

Valores devueltos

Cualquier variable de PHP que pueda ser serializada y almacenada como metainformación del fichero, onullsi no hay metainformación almacenada.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::getMetadata()

<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.txt'] ='hello';
$p['fichero.txt']->setMetadata(array('usuario'=>'bill','tipo-mime'=>'text/plain'));
var_dump($p['fichero.txt']->getMetadata());
} catch (
Exception $e) {
echo
'No se pudo crear y/o modificar nuevo_phar.phar:',$e;
}
?>

El resultado del ejemplo sería:

array(2) {
  ["usuario"]=>
  string(4) "bill"
  ["tipo-mime"]=>
  string(10) "text/plain"
}

Ver también



PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getPharFlagsDevolver las banderas de una entrada de fichero

Descripción

publicPharFileInfo::getPharFlags():int

Este método devuelve las banderas establecidas en el manifiesto de un Phar. Siempre devolverá0en la implementacion actual.

Valores devueltos

Las banderas del Phar (siempre0en la implementacion actual)

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::getPharFlags()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
var_dump($fichero->getPharFlags());
} catch (
Exception $e) {
echo
'No se pudo crear/modificar my.phar: ',$e;
}
?>

El resultado del ejemplo sería:

int(0)



PharFileInfo::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::hasMetadataDevolver la metainformación de una entrada

Descripción

publicPharFileInfo::hasMetadata():bool

Devuelve la metainformación de una fichero dentro de un archivo phar.

Parámetros

No tiene parámetros.

Valores devueltos

Devuelvefalsesi no está establecida la metainformación o esnull,truesi la metainformación no esnull

Ver también



PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCRCCheckedDevolver si la entrada de fichero tiene su CRC verificada

Descripción

publicPharFileInfo::isCRCChecked():bool

Este método devuelve si un fichero dentro de un archivo Phar tiene su CRC verificada.

Valores devueltos

truesi el fichero tiene su CRC verificada,falsesi no.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::isCRCChecked()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$fichero=$p['mifichero.txt'];
var_dump($fichero->isCRCChecked());
} catch (
Exception $e) {
echo
'Las operaciones de creación/modificación sobre mi.phar fallaron: ',$e;
}
?>

El resultado del ejemplo sería:

bool(true)



PharFileInfo::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCompressedDevolver si la entrada está comprimida

Descripción

publicPharFileInfo::isCompressed(int$compression_type= 9021976):bool

Este método devuelve si un fichero está comprimido dentro de un archivo Phar con la compresión Gzip o Bzip2.

Parámetros

compression_type

Una de las constantesPhar::GZoPhar::BZ2, por defecto es cualquier compresión.

Valores devueltos

truesi el fichero está comprimido dentro del archivo Phar,falsesi no.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::isCompressed()

<?php
try {
$p= newPhar('/ruta/a/mi.phar',0,'mi.phar');
$p['mifichero.txt'] ='hola';
$p['mifichero2.txt'] ='hola';
$p['mifichero2.txt']->setCompressedGZ();
$fichero=$p['mifichero.txt'];
$fichero2=$p['mifichero2.txt'];
var_dump($fichero->isCompressed());
var_dump($fichero 2->isCompressed());
} catch (
Exception $e) {
echo
'La creación/modificación del phar mi.phar falló: ',$e;
}
?>

El resultado del ejemplo sería:

bool(false)
bool(true)

Ver también



PharFileInfo::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::setMetadataEstablecer la metainformación específica de un fichero almacenda con un fichero

Descripción

publicPharFileInfo::setMetadata(mixed$metadata):void

PharFileInfo::setMetadata()solamente debería usarse para almacenar información personalizada en un fichero que con pueda ser representado con la información almacenada existente con un fichero. La metainformación puede ralentizar significativamente la velocidad de carga de un archivo phar si la información es grande, o si existen muchos ficheros que contienen metainformación. Es importante observar que esos permisos de fichero están soportados nativamente dentro de un phar; es posible establecerlo con el métodoPharFileInfo::chmod(). Al igual que con toda la funcionalidad que modifica el contenido de un Phar, la variable INIphar.readonlydebe estar desactivada para poder realizar esto si el fichero está dentro de un archivoPhar. Los ficheros dentro de archivosPharDatano tienen esta restricción.

Algunos posibles usos para la metainformación incluten pasar un usuario/grupo que debería establecerse al extraer el fichero desde el phar al disco. Otros usos podrían incluir explicitamente especificar un tipo MIME a devolver. Sin embargo, cualquier información útil que describa un fichero, excepto la que no debería estar contenida dentro del mismo, puede ser almacenada.

Parámetros

metadata

Cualquier variable de PHP que contenga información a almacenar junto a un fichero

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Un ejemplo dePharFileInfo::setMetadata()

<?php
// asegurarse de que no existe
@unlink('nuevo_phar.phar');
try {
$p= newPhar(dirname(__FILE__) .'/nuevo_phar.phar',0,'nuevo_phar.phar');
$p['fichero.txt'] ='hola';
$p['fichero.txt']->setMetadata(array('usuario'=>'bill','tipo-mime'=>'text/plain'));
var_dump($p['fichero.txt']->getMetadata());
} catch (
Exception $e) {
echo
'No se pudo crear y/o modificar el phar:',$e;
}
?>

El resultado del ejemplo sería:

array(2) {
  ["usuario"]=>
  string(4) "bill"
  ["tipo-mime"]=>
  string(10) "text/plain"
}

Ver también


Tabla de contenidos



La clase PharException

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Introducción

La clase PharException ofrece una excepción de clase específica de phar para bloques try/catch.

Sinopsis de la Clase

classPharExceptionextendsException{
/* Propiedades heredadas */
protectedstring$message;
protectedint$code;
protectedstring$file;
protectedint$line;
/* Métodos heredados */
finalpublicException::getMessage():string
finalpublicException::getFile():string
finalpublicException::getLine():int
finalpublicException::getTrace():array
finalpublicException::getTraceAsString():string
publicException::__toString():string
finalprivateException::__clone():void
}

PharException

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharExceptionLa clase PharException ofrece una excepción de clase específica de phar para bloques try/catch

Descripción


Tabla de contenidos

  • PharException— La clase PharException ofrece una excepción de clase específica de phar para bloques try/catch



Archivos Rar


Introducción

Rar es un potente y eficaz archivador creado por Eugene Roshal. Esta extensión proporciona la posibilidad de leer archivos Rar, pero no soporta la escritura de los mismos, ya que no es compatible con la biblioteca UnRar y está directamente prohibido por su licencia.

Se puede encontrar más información sobre Rar y UnRar en» http://www.rarlabs.com/.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna biblioteca externa para compilar esta extensión.



Instalación

Rar está actualmente disponible a través de PECL» https://pecl.php.net/package/rar.

También puede usar el instalador PECL para instalar la extensión Rar, utilizando el siguiente comando:pecl -v install rar.

Siempre puede descargar el paquetetar.gze instalar Rar a mano:

Ejemplo #1 Instalación Rar

gunzip rar-xxx.tgz
tar -xvf rar-xxx.tar
cd rar-xxx
phpize
./configure && make && make install

Los usuarios de Windows habilitaránphp_rar.dllen el interior dephp.inicon el fin de utilizar estas funciones. Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.



Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración definidas enphp.ini.



Tipos de recursos

Esta extensión registra tres clases internas: Las representaciones de archivo devuelto porrar_open()RarArchive–, las representaciones de entrada devuelto porrar_list()yrar_entry_get()RarEntryy el tipo de excepciónRarException.

Esta extensión también registra un recurso de secuencia, llamado "rar" y una envoltura URL llamada "envoltura rar" y registrada bajo el prefijo "rar".




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

RAR_HOST_MSDOS(integer)
UseRarEntry::HOST_MSDOSen su lugar.
RAR_HOST_OS2(integer)
UseRarEntry::HOST_OS2en su lugar.
RAR_HOST_WIN32(integer)
UseRarEntry::HOST_WIN32en su lugar.
RAR_HOST_UNIX(integer)
UseRarEntry::HOST_UNIXen su lugar.
RAR_HOST_BEOS(integer)
UseRarEntry::HOST_BEOSen su lugar.


Ejemplos

Ver tambiénrar://.

Ejemplo #1 Descompresión "al vuelo"

<?php

if (!array_key_exists("i",$_GET) || !is_numeric($_GET["i"]))
die(
"Index unspecified or non-numeric");
$index= (int)$_GET["i"];

$arch=RarArchive::open("example.rar");
if (
$arch===FALSE)
die(
"Cannot open example.rar");

$entries=$arch->getEntries();
if (
$entries===FALSE)
die(
"Cannot retrieve entries");

if (!
array_key_exists($index,$entries))
die(
"No such index:$index");

$orfilename=$entries[$index]->getName();//UTF-8 encoded

$filesize=$entries[$index]->getUnpackedSize();

/* you could check HTTP_IF_MODIFIED_SINCE here and compare with
* $entries[$index]->getFileTime(). You could also send a
* "Last modified" header */

$fp=$entries[$index]->getStream();
if (
$fp===FALSE)
die(
"Cannot open file with index$indexinsided the archive.");

$arch->close();//no longer needed; stream is independent

functiondetectUserAgent() {
if (!
array_key_exists('HTTP_USER_AGENT',$_SERVER))
return
"Other";

$uas=$_SERVER['HTTP_USER_AGENT'];
if (
preg_match("@Opera/@",$uas))
return
"Opera";
if (
preg_match("@Firefox/@",$uas))
return
"Firefox";
if (
preg_match("@Chrome/@",$uas))
return
"Chrome";
if (
preg_match("@MSIE ([0-9.]+);@",$uas,$matches)) {
if (((float)
$matches[1]) >=7.0)
return
"IE";
}

return
"Other";
}

/*
* We have 3 options:
* - For FF and Opera, which support RFC 2231, use that format.
* - For IE and Chrome, use attwithfnrawpctenclong
* (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
* - For the others, convert to ISO-8859-1, if possible
*/
$formatRFC2231='Content-Disposition: attachment; filename*=UTF-8\'\'%s';
$formatDef='Content-Disposition: attachment; filename="%s"';

switch (
detectUserAgent()) {
case
"Opera":
case
"Firefox":
$orfilename=rawurlencode($orfilename);
$format=$formatRFC2231;
break;

case
"IE":
case
"Chrome":
$orfilename=rawurlencode($orfilename);
$format=$formatDef;
break;
default:
if (
function_exists('iconv'))
$orfilename=
@
iconv("UTF-8","ISO-8859-1//TRANSLIT",$orfilename);
$format=$formatDef;
}

header(sprintf($format,$orfilename));
//cannot send error messages from now on (headers already sent)

//replace by real content type, perhaps infering from the file extension
$contentType="application/octet-stream";
header("Content-Type:$contentType");

header("Content-Transfer-Encoding: binary");

header("Content-Length:$filesize");

if (
$_SERVER['REQUEST_METHOD'] =="HEAD")
die();

while (!
feof($fp)) {
$s= @fread($fp,8192);
if (
$s===false)
break;
//useless to send error messages

echo$s;
}
?>

En este ejemplo se obtiene el archivo que contiene el archivo RAR y se ofrece para descargar.

Ejemplo #2 Ejemplo de sistema de extracción de archivos Rar

<?php

$rar_file
=rar_open('example.rar') or die("Can't open Rar archive");

$entries=rar_list($rar_file);

foreach (
$entriesas$entry) {
echo
'Filename: '.$entry->getName() ."\n";
echo
'Packed size: '.$entry->getPackedSize() ."\n";
echo
'Unpacked size: '.$entry->getUnpackedSize() ."\n";

$entry->extract('/dir/extract/to/');
}

rar_close($rar_file);

?>

Este ejemplo extrae cada archivo del archivo Rar en el directorio especificado.



Funciones Rar


rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_statsCaché de aciertos y errores del URL wrapper

Descripción

rar_wrapper_cache_stats():string

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

Esta función no tiene parámetros.

Valores devueltos


Tabla de contenidos



La clase RarArchive

(PECL rar >= 2.0.0)

Introducción

Esta clase representa un archivo RAR que puede estar formado por varios volúmenes (partes) y que contiene una serie de entradas RAR (por ejemplo: archivos, directorios y otros objetos especiales, como enlaces simbólicos).

Los objetos de esta clase puede ser atravesado, dando las entradas almacenadas en el archivo RAR respectivamente. Estas entradas también pueden ser obtenidas medianteRarArchive::getEntry()yRarArchive::getEntries().

Sinopsis de la Clase

finalclassRarArchiveimplementsTraversable{
/* Métodos */
publicclose():bool
publicgetComment():string
publicgetEntries():array
publicgetEntry(string$entryname):RarEntry
publicisBroken():bool
publicisSolid():bool
publicstaticopen(string$filename,string$password= NULL,callable$volume_callback= NULL):RarArchive
publicsetAllowBroken(bool$allow_broken):bool
public__toString():string
}

RarArchive::close

rar_close

(PECL rar >= 2.0.0)

RarArchive::close--rar_closeCerrar archivo RAR y liberar todos los recursos

Descripción

Estilo orientado a objetos (método):

publicRarArchive::close():bool

Estilo por procedimientos:

rar_close(RarArchive$rarfile):bool

Cerar archivo RAR y liberar todos los recursos asignados.

Parámetros

rarfile

Un objetoRarArchive, abierto conrar_open().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
2.0.0Las entradas RAR devueltas porRarArchive::getEntry()yRarArchive::getEntries()son ahora invalidadas cuando se llama a este método. Esto significa que todos los métodos de instancia llamados por tales entradas y no garantizan el éxito.

Ejemplos

Ejemplo #1 Estilo orientado a objetos

<?php
$rar_arch
=RarArchive::open('latest_winrar.rar');
echo
$rar_arch."\n";
$rar_arch->close();
echo
$rar_arch."\n";
?>

El resultado del ejemplo sería algo similar a:

RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

Ejemplo #2 Estilo por procedimientos

<?php
$rar_arch
=rar_open('latest_winrar.rar');
echo
$rar_arch."\n";
rar_close($rar_arch);
echo
$rar_arch."\n";
?>



RarArchive::getComment

rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment--rar_comment_getObtener comentarios de texto desde el archivo RAR

Descripción

Estilo orientado a objetos (method):

publicRarArchive::getComment():string

Estilo por procedimientos:

rar_comment_get(RarArchive$rarfile):string

Obtener (global) comentario almacenado en el archivo RAR. Este puede ser de hasta 64 KiB de longitud.

Nota:

Esta extensión no es compatible con los comentarios en el nivel de entrada.

Parámetros

rarfile

Un objetoRarArchive, abierto conrar_open().

Valores devueltos

Devuelve el comentario onullsi no hay ninguno.

Nota:

RAR no tiene actualmente soporte para comentarios unicode. La codificación de los resultados de esta función no es especificado, pero esta debe ser probablemente Windows-1252.

Ejemplos

Ejemplo #1 Estilo orientado a objetos

<?php
$rar_arch
=RarArchive::open('commented.rar');
echo
$rar_arch->getComment();
?>

El resultado del ejemplo sería algo similar a:

This is the comment of the file commented.rar.

Ejemplo #2 Estilo por procedimientos

<?php
$rar_arch
=rar_open('commented.rar');
echo
rar_comment_get($rar_arch);
?>



RarArchive::getEntries

rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries--rar_listObtener la lista completa de entradas del archivo RAR

Descripción

Estilo orientado a objetos (método):

publicRarArchive::getEntries():array

Estilo por procedimientos:

rar_list(RarArchive$rarfile):array

Obtener la lista de entradas (archivos y directorios) de el archivo RAR.

Nota:

Si el archivo tiene entradas con el mismo nombre, este método, junto conRarArchiveforeachiteraciona y otorga un acceso array-like con índices numéricos, únicos para acceder a todas las entradas (por ejemplo,RarArchive::getEntry()y elrar://wrapperson insuficientes).

Parámetros

rarfile

Un objetoRarArchive, abierto conrar_open().

Valores devueltos

rar_list()devuelve array de objetosRarEntryofalseen caso de error.

Historial de cambios

VersiónDescripción
3.0.0Soporte para archivos RAR con nombres entrada repetidos que ya no produce deficiencias.

Ejemplos

Ejemplo #1 Estilo orientado a objetos

<?php
$rar_arch
=RarArchive::open('solid.rar');
if (
$rar_arch===FALSE)
die(
"Could not open RAR archive.");

$rar_entries=$rar_arch->getEntries();
if (
$rar_entries===FALSE)
die(
"Could retrieve entries.");

echo
"Found ".count($rar_entries) ." entries.\n";

foreach (
$rar_entriesas$e) {
echo
$e;
echo
"\n";
}
$rar_arch->close();
?>

El resultado del ejemplo sería algo similar a:

Found 2 entries.
RarEntry for file "tese.txt" (23b93a7a)
RarEntry for file "unrardll.txt" (2ed64b6e)

Ejemplo #2 Estilo por procedimientos

<?php
$rar_arch
=rar_open('solid.rar');
if (
$rar_arch===FALSE)
die(
"Could not open RAR archive.");

$rar_entries=rar_list($rar_arch);
if (
$rar_entries===FALSE)
die(
"Could retrieve entries.");

echo
"Found ".count($rar_entries) ." entries.\n";

foreach (
$rar_entriesas$e) {
echo
$e;
echo
"\n";
}
rar_close($rar_arch);
?>

Ver también



RarArchive::getEntry

rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry--rar_entry_getObtener el objeto entrada desde el archivo RAR

Descripción

Estilo orientado a objetos (método):

publicRarArchive::getEntry(string$entryname):RarEntry

Estilo por procedimientos:

rar_entry_get(RarArchive$rarfile,string$entryname):RarEntry

Obtener el objeto entrada (archivo o directorio) desde el archivo RAR.

Nota:

También puede obtener objetos de entrada utilizandoRarArchive::getEntries().

Tenga en cuenta que un archivo RAR puede tener varias entradas con el mismo nombre; este método recuperará sólo el primero.

Parámetros

rarfile

Un objetoRarArchive, abierto conrar_open().

entryname

Ruta a la entrada dentro del archivo RAR.

Nota:

La ruta debe ser la misma devuelta porRarEntry::getName().

Valores devueltos

Devuelve el objetoRarEntryencontrado ofalseen caso de error.

Ejemplos

Ejemplo #1 Estilo orientado a objetos

<?php
$rar_arch
=RarArchive::open('solid.rar');
if (
$rar_arch===FALSE)
die(
"Could not open RAR archive.");
$rar_entry=$rar_arch->getEntry('tese.txt');
if (
$rar_entry===FALSE)
die(
"Could get such entry");
echo
get_class($rar_entry)."\n";
echo
$rar_entry;
$rar_arch->close();
?>

El resultado del ejemplo sería algo similar a:

RarEntry
RarEntry for file "tese.txt" (23b93a7a)

Ejemplo #2 Estilo por procedimientos

<?php
$rar_arch
=rar_open('solid.rar');
if (
$rar_arch===FALSE)
die(
"Could not open RAR archive.");
$rar_entry=rar_entry_get($rar_arch,'tese.txt');
if (
$rar_entry===FALSE)
die(
"Could get such entry");
echo
get_class($rar_entry)."\n";
echo
$rar_entry;
rar_close($rar_arch);
?>

Ver también



RarArchive::isBroken

rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken--rar_broken_isComprobar si un archivo está dañado (incompleto)

Descripción

Estilo orientado a objetos (método):

publicRarArchive::isBroken():bool

Estilo por procedimientos:

rar_broken_is(RarArchive$rarfile):bool

Esta función determina si un archivo está incompleto, por ejemplo, Si un volumen no se encuentra o un volumen está truncado.

Parámetros

rarfile

Un objetoRarArchive, abierto conrar_open().

Valores devueltos

Devuelvetruesi el archivo está dañado,falseen caso contrario. Esta función puede también devolverfalsesi el archivo pasado fue cerrado. La única manera para poder distinguir aparte ambos casos es habilitando y permitiendo excepciones conRarException::setUsingExceptions(); sin embargo, esto debería ser innecesario, ya que un programa no debe funcionar con archivos cerrados.

Ejemplos

Ejemplo #1 Estilo orientado a objetos

<?php
functionretnull() { returnnull; }
$file=dirname(__FILE__) ."/multi_broken.part1.rar";
/* El tercer argumento es utilizado para omitir avisos */
$arch=RarArchive::open($file,null,'retnull');
var_dump($arch->isBroken());
?>

El resultado del ejemplo sería algo similar a:

bool(true)

Ejemplo #2 Estilo por procedimientos

<?php
functionretnull() { returnnull; }
$file=dirname(__FILE__) ."/multi_broken.part1.rar";
/* El tercer argumento es utilizado para omitir avisos */
$arch=rar_open($file,null,'retnull');
var_dump(rar_broken_is($arch));
?>

Ver también



RarArchive::isSolid

rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid--rar_solid_isComprueba si el archivo RAR es sólido

Descripción

Estilo orientado a objetos (método):

publicRarArchive::isSolid():bool

Estilo por procedimientos:

rar_solid_is(RarArchive$rarfile):bool

Comprueba si el archivo RAR es sólido. La extracción individual de ficheros es más lenta en archivos sólidos.

Parámetros

rarfile

La instancia delRarArchive, abierto conrar_open().

Valores devueltos

Devuelvetruesi el archivo es sólido, de lo contrario retornafalse.

Ejemplos

Ejemplo #1 Estilo orientado a objetos

<?php
$arch1
=RarArchive::open("store_method.rar");
$arch2=RarArchive::open("solid.rar");
echo
"$arch1: ". ($arch1->isSolid()?'yes':'no') ."\n";
echo
"$arch2: ". ($arch2->isSolid()?'yes':'no') ."\n";
?>

El resultado del ejemplo sería algo similar a:

RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

Ejemplo #2 Estilo por procedimientos

<?php
$arch1
=rar_open("store_method.rar");
$arch2=rar_open("solid.rar");
echo
"$arch1: ". (rar_solid_is($arch1)?'yes':'no') ."\n";
echo
"$arch2: ". (rar_solid_is($arch2)?'yes':'no') ."\n";
?>



RarArchive::open

rar_open

(PECL rar >= 2.0.0)

RarArchive::open--rar_openAbre un archivo RAR

Descripción

Estilo orientado a objetos (método):

publicstaticRarArchive::open(string$filename,string$password= NULL,callable$volume_callback= NULL):RarArchive

Estilo por procedimientos:

rar_open(string$filename,string$password= NULL,callable$volume_callback= NULL):RarArchive

Abre un archivo RAR especificado y devuelve la instanciaRarArchiveque lo representa.

Nota:

Si el archivo a abrir esta dividido en volúmenes, se deberá pasar la ruta del primer volúmen como parámetro de la función. De lo contrario, no todos los archivos se mostraran.

Parámetros

filename

Ruta del archivo Rar.

password

Contraseña en texto plano, si fuera necesario descifrar la cabecera del archivo. También se utilizará por defecto si hay archivos encriptados encontrados. Tenga en cuenta que los archivos pueden poseer diferentes contraseñas en cuanto a las cabeceras y entre ellos.

volume_callback

Una función que recibe como parámetro la ruta del volúmen que no fue encontrado y retorna una cadena con la ruta correcta para dicho archivo onullsi el volúmen no existe o no es conocido. El programador debería asegurar que la función pasada no cause bucles, ya que esta función es llamada repetidas veces si la ruta devuelta en una llamada previa no corresponde con el volúmen solicitado. Especificando este parámetro se omite la notice que se emitiría cuando un volúmen no es encontrado; una implementación que solo devuelvanullpuede, por lo tanto, utilizarce para omitir dichos notices.

Advertencia

En versiones menores a 2.0.0 de PHP, ­esta función no manejaria rutas relativas correctamente. Userealpath()como una solución.

Valores devueltos

Devuelve una instancia delRarArchivesolicitado ofalseen caso de error.

Historial de cambios

VersiónDescripción
3.0.0volume_callbackfue agregada.

Ejemplos

Ejemplo #1 Estilo orientado a objetos

<?php
$rar_arch
=RarArchive::open('encrypted_headers.rar','samplepassword');
if (
$rar_arch===FALSE)
die(
"Failed opening file");

$entries=$rar_arch->getEntries();
if (
$entries===FALSE)
die(
"Failed fetching entries");

echo
"Found ".count($entries) ." files.\n";

if (empty(
$entries))
die(
"No valid entries found.");

$stream=reset($entries)->getStream();
if (
$stream===FALSE)
die(
"Failed opening first file");

$rar_arch->close();

echo
"Content of first one follows:\n";
echo
stream_get_contents($stream);

fclose($stream);
?>

El resultado del ejemplo sería algo similar a:

Found 2 files.
Content of first one follows:
Encrypted file 1 contents.

Ejemplo #2 Estilo por procedimientos

<?php
$rar_arch
=rar_open('encrypted_headers.rar','samplepassword');
if (
$rar_arch===FALSE)
die(
"Failed opening file");

$entries=rar_list($rar_arch);
if (
$entries===FALSE)
die(
"Failed fetching entries");

echo
"Found ".count($entries) ." files.\n";

if (empty(
$entries))
die(
"No valid entries found.");

$stream=reset($entries)->getStream();
if (
$stream===FALSE)
die(
"Failed opening first file");

rar_close($rar_arch);

echo
"Content of first one follows:\n";
echo
stream_get_contents($stream);

fclose($stream);
?>

Ejemplo #3 Volume Callback

<?php
/* En este ejemplo, hay un volúmen llamdo multi_broken.part1.rar
* cuyo próximo volúmen es llamado multi.part2.rar */
functionresolve($vol) {
if (
preg_match('/_broken/',$vol))
return
str_replace('_broken','',$vol);
else
return
null;
}
$rar_file1=rar_open(dirname(__FILE__).'/multi_broken.part1.rar',null,'resolve');
$entry=$rar_file1->getEntry('file2.txt');
$entry->extract(null,dirname(__FILE__) ."/temp_file2.txt");
?>

Ver también



RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBrokenDetermina si la apertura de archivos dañados se permite

Descripción

Estilo orientado a objetos (method):

publicRarArchive::setAllowBroken(bool$allow_broken):bool

Estilo por procedimientos:

rar_allow_broken_set(RarArchive$rarfile,bool$allow_broken):bool

Este método determina si los archivos dañados pueden ser leidos o todas las operaciones que intenten extraer el archivo de las entradas producirán un error. Los archivos rotos son archivos para los cuales ningún error es detectado cuando el archivo es abierto pero un error se produce cuando leemos las entradas.

Parámetros

rarfile

Un objetoRarArchive, abierto conrar_open().

allow_broken

Determina si se permite la lectura de archivos dañados (true) o no (false).

Valores devueltos

Devuelvetrueofalseen caso de error. Sólo se producirá un error si el archivo ya fue cerrado.

Ejemplos

Ejemplo #1 Estilo orientado a objetos

<?php
functionretnull() { returnnull; }
$file=dirname(__FILE__) ."/multi_broken.part1.rar";
/* El tercer argumento omite el mensaje "volumen no encontrado" */
$a=RarArchive::open($file,null,'retnull');
$a->setAllowBroken(true);
foreach (
$a->getEntries() as$e) {
echo
"$e\n";
}
var_dump(count($a));
?>

El resultado del ejemplo sería algo similar a:

RarEntry for file "file1.txt" (52b28202)
int(1)

Ejemplo #2 Estilo por procedimientos

<?php
functionretnull() { returnnull; }
$file=dirname(__FILE__) ."/multi_broken.part1.rar";
/* El tercer argumento omite el mensaje "volumen no encontrado" */
$a=rar_open($file,null,'retnull');
rar_allow_broken_set($a,true);
foreach (
rar_list($a) as$e) {
echo
"$e\n";
}
var_dump(count($a));
?>

Ver también



RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toStringObtener representación de texto

Descripción

publicRarArchive::__toString():string

Proporciona una representación de cadena para este objetoRarArchive. Esta actualmente muestra la ruta completa del volumen de archivo que fue abierto y si el recurso es válido o ya estaba cerrado a través de una llamada aRarArchive::close().

Este método debe ser utilizado sólo para propósitos de depuración, ya que no existen garantías en cuanto a la información que contiene el resultado o cómo esta es formateada.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Una representación textual de este objetoRarArchive. El contenido de esta representación no es especificado.

Ejemplos

Ejemplo #1 Ejemplo deRarArchive::__toString()

<?php
$rar_arch
=RarArchive::open('latest_winrar.rar');
echo
$rar_arch."\n";
$rar_arch->close();
echo
$rar_arch."\n";
?>

El resultado del ejemplo sería algo similar a:

RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)


Tabla de contenidos



La claseRarEntry

(PECL rar >= 0.1)

Introducción

Una entrada RAR, representa un directorio o un archivo comprimido dentro de un archivo RAR.

Sinopsis de la Clase

finalclassRarEntry{
/* Constantes */
constintegerHOST_MSDOS= 0;
constintegerHOST_OS2= 1;
constintegerHOST_WIN32= 2;
constintegerHOST_UNIX= 3;
constintegerHOST_MACOS= 4;
constintegerHOST_BEOS= 5;
constintegerATTRIBUTE_WIN_READONLY= 1;
constintegerATTRIBUTE_WIN_HIDDEN= 2;
constintegerATTRIBUTE_WIN_SYSTEM= 4;
constintegerATTRIBUTE_WIN_DIRECTORY= 16;
constintegerATTRIBUTE_WIN_ARCHIVE= 32;
constintegerATTRIBUTE_WIN_DEVICE= 64;
constintegerATTRIBUTE_WIN_NORMAL= 128;
constintegerATTRIBUTE_WIN_TEMPORARY= 256;
constintegerATTRIBUTE_WIN_SPARSE_FILE= 512;
constintegerATTRIBUTE_WIN_REPARSE_POINT= 1024;
constintegerATTRIBUTE_WIN_COMPRESSED= 2048;
constintegerATTRIBUTE_WIN_OFFLINE= 4096;
constintegerATTRIBUTE_WIN_ENCRYPTED= 16384;
constintegerATTRIBUTE_WIN_VIRTUAL= 65536;
constintegerATTRIBUTE_UNIX_GROUP_READ= 32;
constintegerATTRIBUTE_UNIX_OWNER_WRITE= 128;
constintegerATTRIBUTE_UNIX_OWNER_READ= 256;
constintegerATTRIBUTE_UNIX_STICKY= 512;
constintegerATTRIBUTE_UNIX_SETGID= 1024;
constintegerATTRIBUTE_UNIX_SETUID= 2048;
constintegerATTRIBUTE_UNIX_FINAL_QUARTET= 61440;
constintegerATTRIBUTE_UNIX_FIFO= 4096;
constintegerATTRIBUTE_UNIX_CHAR_DEV= 8192;
constintegerATTRIBUTE_UNIX_DIRECTORY= 16384;
constintegerATTRIBUTE_UNIX_BLOCK_DEV= 24576;
constintegerATTRIBUTE_UNIX_REGULAR_FILE= 32768;
constintegerATTRIBUTE_UNIX_SYM_LINK= 40960;
constintegerATTRIBUTE_UNIX_SOCKET= 49152;
/* Métodos */
publicextract(
    string$dir,
    string$filepath= "",
    string$password= NULL,
    bool$extended_data= false
):bool
publicgetAttr():int
publicgetCrc():string
publicgetFileTime():string
publicgetHostOs():int
publicgetMethod():int
publicgetName():string
publicgetPackedSize():int
publicgetStream(string$password= ?):resource
publicgetUnpackedSize():int
publicgetVersion():int
publicisDirectory():bool
publicisEncrypted():bool
public__toString():string
}

Constantes predefinidas

RarEntry::HOST_MSDOS

Si el valor devuelto porRarEntry::getHostOs()es igual a esta constante, MS-DOS fue utilizado para añadir esta entrada. Utilizar en lugar deRAR_HOST_MSDOS.

RarEntry::HOST_OS2

Si el valor devuelto porRarEntry::getHostOs()es igual a esta constante, OS/2 fue utilizado para añadir esta entrada. Destinado para sustituir aRAR_HOST_OS2.

RarEntry::HOST_WIN32

Si el valor devuelto porRarEntry::getHostOs()es igual a esta constante, Microsoft Windows fue utilizado para añadir esta entrada. Destinado para sustituir aRAR_HOST_WIN32.

RarEntry::HOST_UNIX

Si el valor devuelto porRarEntry::getHostOs()es igual a esta constante, un Sistema Operativo UNIX no especificado fue utilizado para añadir esta entrada. Destinado para sustituir aRAR_HOST_UNIX.

RarEntry::HOST_MACOS

Si el valor devuelto porRarEntry::getHostOs()es igual a esta constante, un Sistema Operativo Mac fue utilizado para añadir esta entrada.

RarEntry::HOST_BEOS

Si el valor devuelto porRarEntry::getHostOs()es igual a esta constante, un Sistema Operativo BeOS fue utilizado para añadir esta entrada. Destinado para sustituir aRAR_HOST_BEOS.

RarEntry::ATTRIBUTE_WIN_READONLY

Bit que representa una entrada de Windows con un atributo de sólo lectura. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_HIDDEN

Bit que representa una entrada de Windows con un atributo oculto. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_SYSTEM

Bits que representa una entrada de Windows con un atributo del sistema. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_DIRECTORY

Bit que representa una entrada de Windows con un atributo de directorio (entrada es un directorio). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows. Véase tambiénRarEntry::isDirectory(), que también trabaja con entradas que no fueron añadidas en WinRAR.

RarEntry::ATTRIBUTE_WIN_ARCHIVE

Bit que representa una entrada de Windows con un atributo de archivo. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_DEVICE

Bit que representa una entrada de Windows con un atributo de dispositivo. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_NORMAL

Bit que representa una entrada de Windows con un atributo de archivo normal (entrada NO es un directorio). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows. Véase tambiénRarEntry::isDirectory(), que también trabaja con entradas que no fueron añadidas en WinRAR.

RarEntry::ATTRIBUTE_WIN_TEMPORARY

Bit que representa una entrada de Windows con un atributo temporal. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_SPARSE_FILE

Bit que representa una entrada de Windows con un atributo de archivo disperso (archivo es un archivo disperso NTFS). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_REPARSE_POINT

Bit que representa una entrada de Windows con un atributo punto de re-análisis (entrada es un punto de re-análisis NTFS, por ejemplo, un directorio enlace o un sistema de montaje de archivos). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_COMPRESSED

Bit que representa una entrada de Windows con un atributo comprimido (sólo NTFS). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_OFFLINE

Bit que representa una entrada de Windows con un atributo fuera de línea (entrada es desconectada y no accesible). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED

Bit que representa una entrada de Windows con un atributo de contenido no indexado (entrada deberá ser indexada). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_ENCRYPTED

Bit que representa una entrada de Windows con un atributo cifrado (sólo NTFS). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_VIRTUAL

Bit que representa una entrada de Windows con un atributo virtual. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es Microsoft Windows.

RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE

Bit que representa una entrada que es ejecutable en el mundo UNIX. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE

Bit que representa una entrada que es escribible en el mundo UNIX. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_WORLD_READ

Bit que representa una entrada que es leible en el mundo UNIX. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE

Bit que representa una entrada UNIX que es grupo ejecutable. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE

Bit que representa una entrada UNIX que es grupo escribible. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_READ

Bit que representa una entrada UNIX que es grupo leible. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE

Bit que representa una entrada UNIX que es propietario ejecutable. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE

Bit que representa una entrada UNIX que es propietario escribible. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_READ

Bit que representa una entrada UNIX que es propietario leible. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_STICKY

Bit que representa el sticky bit UNIX. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_SETGID

Bit que representa el atributo UNIX setgid. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_SETUID

Bit que representa el atributo UNIX setuid. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX.

RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET

Máscara para aislar a los últimos cuatro bits (nibble) de atributos UNIX (_S_IFMT, el tipo de máscara de archivo). Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con las constantesRarEntry::ATTRIBUTE_UNIX_FIFO,RarEntry::ATTRIBUTE_UNIX_CHAR_DEV,RarEntry::ATTRIBUTE_UNIX_DIRECTORY,RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV,RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE,RarEntry::ATTRIBUTE_UNIX_SYM_LINKandRarEntry::ATTRIBUTE_UNIX_SOCKET.

RarEntry::ATTRIBUTE_UNIX_FIFO

FIFOs Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_CHAR_DEV

Dispositivo de tipo carácter Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_DIRECTORY

Directorios Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. Véase tambiénRarEntry::isDirectory(), que también trabaja con entradas que fueron añadidas en otros sistemas operativos.

RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV

Dispositivo de tipo bloque Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE

Archivos regular Unix (no directorios) tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. Véase tambiénRarEntry::isDirectory(), ue también trabaja con entradas que fueron añadidas en otros sistemas operativos.

Enlace simbólico Unix tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_SOCKET

Sockets Unix will tendrá atributos cuyos últimos cuatro bits tienen este valor. Para ser utilizado conRarEntry::getAttr()en entradas cuyo sistema operativo anfitrión es UNIX y con la constanteRarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.


RarEntry::extract

(PECL rar >= 0.1)

RarEntry::extractExtraer entrada del archivo

Descripción

publicRarEntry::extract(
    string$dir,
    string$filepath= "",
    string$password= NULL,
    bool$extended_data= false
):bool

RarEntry::extract()extrae los datos de entrada. Esto creará un nuevo archivo en eldirespecificado con el mismo nombre que el nombre de la entrada, a menos que el segundo argumento sea especificado. Siga leyendo más abajo para obtener mayor información.

Parámetros

dir

Ruta al directorio donde los archivos deben ser extraídos. Este parámetro es considerado si y sólo si no esfilepath. Si ambos parámetros están vacíos se intentará una extracción en el directorio actual.

filepath

Ruta (relativa o absoluta) que contiene el directorio y el nombre del archivo extraído. Este parámetro anula los parámetrosdiry el nombre del archivo original.

password

La contraseña utilizada para cifrar esta entrada. Si la entrada no está cifrada, este valor no se utilizará y puede ser omitido. Si se omite este parámetro y la entrada está cifrada, la contraseña dada arar_open(), será utlizada. Si una contraseña incorrecta es dada, de forma explicita o implicita viarar_open(), la comprobación CRC fallará y este método fallará y devolveráfalse. Si no se da la contraseña y se requiere una, este método fallará y devolveráfalse. Puede comprobar si una entrada está cifrada conRarEntry::isEncrypted().

extended_data

Sitrue, información extendida tales como NTFS ACLs e información propietaria Unix será establecida en los archivos extraidos, siempre que esta esté presente en el archivo.

Advertencia

Antes de la versión 2.0.0, esta función no manejaba las rutas relativas correctamente. Utilicerealpath()como una solución.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
3.0.0extended_datafue añadido.
3.0.0Soporte para archivos RAR con nombres de entrada que se repiten ya no es defectuoso

Ejemplos

Ejemplo #1 Ejemplo deRarEntry::extract()

<?php

$rar_file
=rar_open('example.rar') or die("Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");

$entry->extract('/dir/to');// crear /dir/to/Dir/file.txt
$entry->extract(false,'/dir/to/new_name.txt');// crear /dir/to/new_name.txt

?>

Ejemplo #2 ¿Cómo extraer todos los archivos en archivo?:

<?php

/* ejemplo por Erik Jenssen también conocido como erix */

$filename="foobar.rar";
$filepath="/home/foo/bar/";

$rar_file=rar_open($filepath.$filename);
$list=rar_list($rar_file);
foreach(
$listas$file) {
$entry=rar_entry_get($rar_file,$file);
$entry->extract(".");// extraer el directorio actual
}
rar_close($rar_file);

?>

Ver también



RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttrObtener los atributos de la entrada

Descripción

publicRarEntry::getAttr():int

Devuelve los atributos dependientes del SO del archivo de entrada.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve los atributos ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deRarEntry::getAttr()

<?php

$rar_file
=rar_open('example.rar') or die("Can't open Rar archive");

$entry=rar_entry_get($rar_file,'dir/in/the/archive') or die("Can't find such entry");

$host_os=$entry->getHostOs();
$attr=$entry->getAttr();

switch(
$host_os) {
case
RAR_HOST_MSDOS:
case
RAR_HOST_OS2:
case
RAR_HOST_WIN32:
case
RAR_HOST_MACOS:
printf("%c%c%c%c%c%c\n",
(
$attr&0x08) ?'V':'.',
(
$attr&0x10) ?'D':'.',
(
$attr&0x01) ?'R':'.',
(
$attr&0x02) ?'H':'.',
(
$attr&0x04) ?'S':'.',
(
$attr&0x20) ?'A':'.');
break;
case
RAR_HOST_UNIX:
case
RAR_HOST_BEOS:
switch (
$attr&0xF000)
{
case
0x4000:
printf("d");
break;
case
0xA000:
printf("l");
break;
default:
printf("-");
break;
}
printf("%c%c%c%c%c%c%c%c%c\n",
(
$attr&0x0100) ?'r':'-',
(
$attr&0x0080) ?'w':'-',
(
$attr&0x0040) ? (($attr&0x0800) ?'s':'x'):(($attr&0x0800) ?'S':'-'),
(
$attr&0x0020) ?'r':'-',
(
$attr&0x0010) ?'w':'-',
(
$attr&0x0008) ? (($attr&0x0400) ?'s':'x'):(($attr&0x0400) ?'S':'-'),
(
$attr&0x0004) ?'r':'-',
(
$attr&0x0002) ?'w':'-',
(
$attr&0x0001) ?'x':'-');
break;
}

rar_close($rar_file);

?>

Ver también



RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrcObtener el CRC de la entrada

Descripción

publicRarEntry::getCrc():string

Devuelve una cadena hexadecimal representación de el CRC del archivo de entrada.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el CRC del archivo de entrada ofalseen caso de error.

Historial de cambios

VersiónDescripción
2.0.0Este método devuelve ahora valores correctos para archivos de varios volúmenes.



RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTimeDevolver entrada última fecha de modificación

Descripción

publicRarEntry::getFileTime():string

Devuelve entrada última fecha modificación.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve entrada última fecha de modificación como una cadena en formatoYYYY-MM-DD HH:II:SS, ofalseen caso de error.



RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOsObtener sistema operativo anfitrión del archivo de entrada

Descripción

publicRarEntry::getHostOs():int

Devuelve el código del sistema operativo anfitrión del archivo de entrada.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el código del sistema operativo anfitrión, ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deRarEntry::getHostOs()(version >= 2.0.0)

<?php

$rar_file
=rar_open('example.rar') or die("Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");

switch (
$entry->getHostOs()) {
case
RarEntry::HOST_MSDOS:
echo
"MS-DOS\n";
break;
case
RarEntry::HOST_OS2:
echo
"OS2\n";
break;
case
RarEntry::HOST_WIN32:
echo
"Win32\n";
break;
case
RarEntry::HOST_MACOS:
echo
"MacOS\n";
break;
case
RarEntry::HOST_UNIX:
echo
"Unix/Linux\n";
break;
case
RarEntry::HOST_BEOS:
echo
"BeOS\n";
break;
}

?>

Ejemplo #2RarEntry::getHostOs()example (version <= 1.0.0)

<?php

$rar_file
=rar_open('example.rar') or die("Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");

switch (
$entry->getHostOs()) {
case
RAR_HOST_MSDOS:
echo
"MS-DOS\n";
break;
case
RAR_HOST_OS2:
echo
"OS2\n";
break;
case
RAR_HOST_WIN32:
echo
"Win32\n";
break;
case
RAR_HOST_MACOS:
echo
"MacOS\n";
break;
case
RAR_HOST_UNIX:
echo
"Unix/Linux\n";
break;
case
RAR_HOST_BEOS:
echo
"BeOS\n";
break;
}

?>

Ver también



RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethodObtener método pack de la entrada

Descripción

publicRarEntry::getMethod():int

RarEntry::getMethod()devuelve el número del método utilizado cuando añadimos archivo actual de entrada.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el número de método ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deRarEntry::getMethod()

<?php

$rar_file
=rar_open('example.rar') or die("Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");

echo
"Method number: ".$entry->getMethod();

?>



RarEntry::getName

(PECL rar >= 0.1)

RarEntry::getNameObtener el nombre de la entrada

Descripción

publicRarEntry::getName():string

Devuelve el nombre (con la ruta) de el archivo entrada.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre de la entrada como una cadena, ofalseen caso de error.

Historial de cambios

VersiónDescripción
2.0.0Desde la versión 2.0.0, la cadena devuelta está codificada en Unicode/UTF-8.

Ejemplos

Ejemplo #1 Ejemplo deRarEntry::getName()

<?php

//este ejemplo, es seguro, incluso en páginas no codificados en UTF-8
//para esa codificación en UTF-8, la llamada a mb_convert_encoding es innecesaria.

$rar_file=rar_open('example.rar') or die("Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");

echo
"Entry name: ".mb_convert_encoding(
htmlentities(
$entry->getName(),
ENT_COMPAT,
"UTF-8"
),
"HTML-ENTITIES",
"UTF-8"
);

?>



RarEntry::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSizeObtiene el tamaño empaquetado de la entrada

Descripción

publicRarEntry::getPackedSize():int

Obtiene el tamaño empaquetado del archivo entrada.

Nota:

Tenga en cuenta que en las plataformas de 32 bits de longitud (que incluye Windows x64), el tamaño máximo devuelto está limitado a 2 GB. Compruebe la constantePHP_INT_MAX.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el tamaño empaquetado, ofalseen caso de error.

Historial de cambios

VersiónDescripción
2.0.0Este método devuelve ahora los valores correctos de empaquetado mayores a 2 GB en plataformas de 64-bitintegers y nunca devuelve valores negativos en otras plataformas.

Ejemplos

Ejemplo #1 Ejemplo deRarEntry::getPackedSize()

<?php

$rar_file
=rar_open('example.rar') or die("Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");

echo
"Packed size of ".$entry->getName() ." = ".$entry->getPackedSize() ." bytes";

?>



RarEntry::getStream

(PECL rar >= 2.0.0)

RarEntry::getStreamObtener manejador de archivo para entrada

Descripción

publicRarEntry::getStream(string$password= ?):resource

Devuelve un manejador de archivo que soporta operaciones de lectura. Este manejador proporciona descompresión al vuelo para esta entrada.

El manejador no es invalidado por llamar arar_close().

Advertencia

El flujo resultante no tiene verificación de integridad. En particular, archivo corrupto y descifrado con una clave errónea, no será detectado. Es responsabilidad del programador utilizar la entrada CRC para comprobar la integridad, si así lo desea.

Parámetros

password

La contraseña utilizada para cifrar esta entrada. Si la entrada no está cifrada, este valor no se utilizará y puede ser omitido. Si el parámetro es omitido y la entrada está cifrada, la contraseña dada arar_open(), será utilizada. Si una contraseña incorrecta es dada, ya sea explícita o implícitamente viarar_open(), teste método resultante de flujo producirá error de salida. Si no se especifica la contraseña y se requiere una, este método fallará y devolveráfalse. Puede comprobar si una entrada está cifrada conRarEntry::isEncrypted().

Valores devueltos

El manejador de archivo ofalseen caso de error.

Historial de cambios

VersiónDescripción
3.0.0Soporte para archivos RAR con nombres de entrada que se repiten ya no es defectuoso.

Ejemplos

Ejemplo #1 Ejemplo deRarEntry::getStream()

<?php

$rar_file
=rar_open('example.rar');
if (
$rar_file===false)
die(
"Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt');
if (
$entry===false)
die(
"Failed to find such entry");

$stream=$entry->getStream();
if (
$stream===false)
die(
"Failed to obtain stream.");

rar_close($rar_file);//flujo es independiente de archivo

while (!feof($stream)) {
$buff=fread($stream,8192);
if (
$buff!==false)
echo
$buff;
else
break;
//error fread
}

fclose($stream);

?>

Ver también



RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSizeObtener el tamaño descomprimido de la entrada

Descripción

publicRarEntry::getUnpackedSize():int

Obtiene el tamaño descomprimido del archivo entrada.

Nota:

Tenga en cuenta que en las plataformas de 32 bits de longitud (que incluye Windows x64), el tamaño máximo devueltos está limitado a 2 GB. Compruebe la constantePHP_INT_MAX.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el tamaño descomprimido, ofalseen caso de error.

Historial de cambios

VersiónDescripción
2.0.0Este método devuelve ahora valores correctos de tamaño descomprimido superiores a 2 GB en plataformas con 64-bitintegers y nunca devuelve valores negativos en otras plataformas.

Valores devueltos

Ejemplo #1 Ejemplo deRarEntry::getUnpackedSize()

<?php

$rar_file
=rar_open('example.rar') or die("Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");

echo
"Unpacked size of ".$entry->getName() ." = ".$entry->getPackedSize() ." bytes";

?>



RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersionObtener la versión mínima del programa RAR requerida para desempaquetar la entrada

Descripción

publicRarEntry::getVersion():int

Devuelve la versión mínima del programa RAR (por ejemplo WinRAR) requerida para desempaquetar la entrada. Esta es codificada como 10 * version mayor + versión menor.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la versión ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deRarEntry::getVersion()

<?php

$rar_file
=rar_open('example.rar') or die("Failed to open Rar archive");

$entry=rar_entry_get($rar_file,'Dir/file.txt') or die("Failed to find such entry");

echo
"Rar version required for unpacking: ".$entry->getVersion();

?>



RarEntry::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectoryComprobar si una entrada representa un directorio

Descripción

publicRarEntry::isDirectory():bool

Comprueba si una entrada representa un directorio.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetruesi la entrada es un directorio yfalseen caso contrario.

Notas

Esta función sólo está disponible desde la versión 2.0.0, pero también puede comprobarse si una entrada es un directorio mediante la comprobación de los atributos de entrada, así (sólo funciona para los archivos comprimidos en RAR por Windows o Unix):

<?php
//...
//Abrir archivo, obtener la entrada y almacenarla en la variable $e...
//...

$isDirectory= (bool) ((($e->getHostOs() ==RAR_HOST_WIN32) && ($e->getAttr() &0x10)) ||
((
$e->getHostOs() ==RAR_HOST_UNIX) && (($e->getAttr() &0xf000) ==0x4000)));
?>



RarEntry::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncryptedComprobar si una entrada está cifrada

Descripción

publicRarEntry::isEncrypted():bool

Comprueba si el contenido de la entrada actual está cifrado.

Nota:

La contraseña utilizada puede variar entre los archivos dentro del mismo archivo RAR.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetruesi la entrada actual se encuentra cifrada yfalseen caso contrario.



RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toStringObtener texto representación de entrada

Descripción

publicRarEntry::__toString():string

RarEntry::__toString()devuelve una representación textual de esta entrada. Esta incluye si la entrada es un archivo o un directorio (enlaces simbólicos y otros objetos especiales serán tratados como archivos), el nombre UTF-8 de la entrada y su CRC. La forma y el contenido de esta representación puede cambiar en el futuro, así que no son fiables.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Una representación textual de la entrada.


Tabla de contenidos



La clase RarException

(PECL rar >= 2.0.0)

Introducción

Esta clase sirve para dos propósitos: estas son el tipo de las excepciones lanzadas por la extensión RAR funciones y métodos y esto permite, a través de métodos estáticos consultar y definir el error y el comportamiento de la extensión, por ejemplo, si las excepciones son lanzadas o solamente se emiten advertencias.

Los códigos de error que se utilizan los siguientes:

  • -1 - error fuera de biblioteca UnRAR
  • 11 - memoria insuficiente
  • 12 - datos dañados
  • 13 - archivo dañado
  • 14 - formato desconocido
  • 15 - error de apertura de archivo
  • 16 - error al crear archivo
  • 17 - error al cerrar archivo
  • 18 - error de lectura
  • 19 - error de escritura
  • 20 - búfer demasiado pequeño
  • 21 - error RAR desconocido
  • 22 - contraseña requerida pero no especificada

Sinopsis de la Clase

finalclassRarExceptionextendsException{
/* Métodos */
publicstaticisUsingExceptions():bool
publicstaticsetUsingExceptions(bool$using_exceptions):void
/* Métodos heredados */
finalpublicException::getMessage():string
finalpublicException::getFile():string
finalpublicException::getLine():int
finalpublicException::getTrace():array
finalpublicException::getTraceAsString():string
publicException::__toString():string
finalprivateException::__clone():void
}

RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptionsComprobar si el manejador de errores con excepciones está en uso

Descripción

publicstaticRarException::isUsingExceptions():bool

Comprueba si las funciones RAR emitirán avisos y devolverán valores de error o si ellas lanzarán excepciones en la mayoría de las circunstancias (no incluye algunos errores de programación tales como pasar el tipo incorrecto de argumento).

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetruesi las excepciones estan siendo utilizadas,falseen caso contrario.

Ejemplos

Ejemplo #1 Ejemplo deRarException::isUsingExceptions()

<?php
//El valor predeterminado es no usar excepciones
var_dump(RarException::isUsingExceptions());
?>

El resultado del ejemplo sería algo similar a:

bool(false)

Ver también



RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptionsActivar y desactivar el manejador de errores con excepciones

Descripción

publicstaticRarException::setUsingExceptions(bool$using_exceptions):void

Si y sólo si el argumento estrue, entonces, en lugar de emitir advertencias y devolver un valor especial indicando error cuando la biblioteca UnRAR encuentre un error, una excepción de tipoRarExceptionserá lanzada.

Las excepciones también será lanzado para los siguientes errores, que se producen fuera de la biblioteca (su código de error será -1):

Parámetros

using_exceptions

Debe sertruepara activar lanzamiento de excepciones,falsepara descativarlo (el valor por defecto).

Ejemplos

Ejemplo #1 Ejemplo deRarException::setUsingExceptions()

<?php
var_dump
(RarException::isUsingExceptions());
$arch=RarArchive::open("does_not_exist.rar");
var_dump($arch);

RarException::setUsingExceptions(true);
var_dump(RarException::isUsingExceptions());
$arch=RarArchive::open("does_not_exist.rar");
var_dump($arch);//not reached
?>

El resultado del ejemplo sería algo similar a:

bool(false)

Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
bool(false)
bool(true)

Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
Stack trace:
#0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
#1 {main}
  thrown in C:\php_rar\trunk\tests\test.php on line 8

Ver también


Tabla de contenidos




Zip


Introducción

Esta extensión permite leer o escribir de forma transparente archivos comprimidos ZIP y los ficheros que hay dentro.



Instalación/Configuración

Tabla de contenidos


Requerimientos

PHP 5.2.0 or later

Esta extensión usa las funciones de» zlibpor Jean-loup Gailly y Mark Adler.



Instalación

PHP 5.2.0 o superior

Sistemas Linux

Para poder utilizar estas funciones, se debe compilar PHP con soporte para zip usando la opción de configuración--enable-zip.

Windows

Los usuarios de Windows deben habilitarphp_zip.dlldentro del ficherophp.inipara poder usar estas funciones.

Instalación mediante PECL

Se puede encontrar información para la instalación de esta extensión PECL en el capítulo del manual tituladoInstalación de extensiones PECL. Se puede encontrar información adicional, tal como nuevos lanzamientos, descargas, ficheros fuente, información de mantenimiento, y un CHANGELOG, aquí:» https://pecl.php.net/package/zip.

Actualmente, no hay ningunaDLLdisponible para esta extensiónPECL. Véase también la secciónCompilación en Windows.



Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración definidas enphp.ini.



Tipos de recursos

Existen dos tipos de recursos usados en el módulo Zip. El primero es el directorio Zip para el fichero Zip, el segundo la entrada Zip para la entrada de archivos.




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

ZipArchiveusa constantes de clase. Existen tres tipos de constantes: Flags (prefijadas conFL_), errores (prefijados conER_) y modos (sin prefijo).

ZipArchive::CREATE(integer)
Crea el archivo si no existe.
ZipArchive::OVERWRITE(integer)
Si existe un archivo, ignora su contenido actual. En otras palabras, lo trata de la misma manera que un archivo vacío.
ZipArchive::EXCL(integer)
Error si el fichero ya existe.
ZipArchive::RDONLY(integer)
Abrir archivo en modo de solo lectura. Disponible a partir de PHP 7.4.3 y PECL zip 1.17.1, respectivamente, si se compila con libzip ≥ 1.0.0.
ZipArchive::CHECKCONS(integer)
Realiza comprobaciones de coherencia adicionales al archivo, producirá un error si falla.
ZipArchive::FL_NOCASE(integer)
Ignorar mayúsculas el lookup del nombre
ZipArchive::FL_NODIR(integer)
Ignorar el componente directorio
ZipArchive::FL_COMPRESSED(integer)
Leer datos comprimidos
ZipArchive::FL_UNCHANGED(integer)
Usar los datos originales, ignorando cambios.
ZipArchive::FL_RECOMPRESS(integer)
Forzar la recompresión de los datos. Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
ZipArchive::FL_ENCRYPTED(integer)
Leer datos encriptados (implica FL_COMPRESSED). Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
ZipArchive::FL_OVERWRITE(integer)
Si existe un archivo con nombre, sobrescríbalo (reemplácelo). Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
ZipArchive::FL_LOCAL(integer)
En la cabecera local. Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
ZipArchive::ZIP_FL_CENTRAL(integer)
En el directorio central. Disponible a partir de PHP 8.0.0 y PECL zip 1.18.0.
ZipArchive::FL_ENC_GUESS(integer)
Codificación de la cadena de suposición (guess string) (predeterminado). Disponible a partir de PHP 7.0.8.
ZipArchive::FL_ENC_RAW(integer)
Obtener la cadena sin modificaciones. Disponible a partir de PHP 7.0.8.
ZipArchive::FL_ENC_STRICT(integer)
Seguir la especificación estrictamente. Disponible a partir de PHP 7.0.8.
ZipArchive::FL_ENC_UTF_8(integer)
La cadena está codificada en UTF-8. Disponible a partir de PHP 7.0.8.
ZipArchive::FL_ENC_CP437(integer)
La cadena está codifica en CP437. Disponible a partir de PHP 7.0.8.
ZipArchive::CM_DEFAULT(integer)
Mejor para desinflar o almacenar.
ZipArchive::CM_STORE(integer)
almacenar (no comprimir).
ZipArchive::CM_SHRINK(integer)
Reducir
ZipArchive::CM_REDUCE_1(integer)
reducido con factor 1
ZipArchive::CM_REDUCE_2(integer)
reducido con factor 2
ZipArchive::CM_REDUCE_3(integer)
reducido con factor 3
ZipArchive::CM_REDUCE_4(integer)
reducido con factor 4
ZipArchive::CM_IMPLODE(integer)
implodado
ZipArchive::CM_DEFLATE(integer)
Deflactado
ZipArchive::CM_DEFLATE64(integer)
deflate64
ZipArchive::CM_PKWARE_IMPLODE(integer)
PKWARE imploding
ZipArchive::CM_BZIP2(integer)
usar algoritmo BZIP2
ZipArchive::CM_LZMA(integer)
Algoritmo LZMA
ZipArchive::CM_LZMA2(integer)
Algoritmo LZMA2. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.0, respectivamente, si se compila con libzip ≥ 1.6.0.
ZipArchive::CM_XZ(integer)
Algoritmo XZ. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.6.0.
ZipArchive::ER_OK(integer)
Sin errores.
ZipArchive::ER_MULTIDISK(integer)
Archivos zip multi-disk no soportados.
ZipArchive::ER_RENAME(integer)
Mantener fichero temporal fallado.
ZipArchive::ER_CLOSE(integer)
Cerrar fichero zip fallado.
ZipArchive::ER_SEEK(integer)
Buscar error
ZipArchive::ER_READ(integer)
Leer error
ZipArchive::ER_WRITE(integer)
Escribir error
ZipArchive::ER_CRC(integer)
error CRC
ZipArchive::ER_ZIPCLOSED(integer)
Conteniendo el fichero zip que ha sido cerrado
ZipArchive::ER_NOENT(integer)
No existe el fichero.
ZipArchive::ER_EXISTS(integer)
El fichero ya existe
ZipArchive::ER_OPEN(integer)
No se puede abrir el fichero
ZipArchive::ER_TMPOPEN(integer)
Fallo al intentar crear fichero temporal.
ZipArchive::ER_ZLIB(integer)
Error de Zlib
ZipArchive::ER_MEMORY(integer)
Error de asignación de memoria
ZipArchive::ER_CHANGED(string)
La entrada a cambiado
ZipArchive::ER_COMPNOTSUPP(integer)
Método de compresión no soportado.
ZipArchive::ER_EOF(integer)
EOF precoz.
ZipArchive::ER_INVAL(integer)
Argumento inválido
ZipArchive::ER_NOZIP(integer)
No es un archivo zip
ZipArchive::ER_INTERNAL(integer)
Error interno
ZipArchive::ER_INCONS(integer)
Fichero Zip inconsistente
ZipArchive::ER_REMOVE(integer)
No se puede eliminar el fichero
ZipArchive::ER_DELETED(integer)
La entrada ha sido eliminada
ZipArchive::ER_ENCRNOTSUPP(integer)
No se admite el método de cifrado. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente.
ZipArchive::ER_RDONLY(integer)
Archivo de sólo lectura. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente.
ZipArchive::ER_NOPASSWD(integer)
No se ha proporcionado ninguna contraseña. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente.
ZipArchive::ER_WRONGPASSWD(integer)
Contraseña incorrecta proporcionada. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente.
ZipArchive::ZIP_ER_OPNOTSUPP(integer)
Operación no soportada. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.0.0.
ZipArchive::ZIP_ER_INUSE(integer)
Recurso todavía en uso. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.0.0.
ZipArchive::ZIP_ER_TELL(integer)
Diga error. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.0.0.
ZipArchive::ZIP_ER_COMPRESSED_DATA(integer)
Los datos comprimidos no son válidos. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.6.0.
ZipArchive::ER_CANCELLED(integer)
Operación cancelada. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.1, respectivamente, si se compila con libzip ≥ 1.6.0.
ZipArchive::EM_NONE(integer)
No hay encriptación. Disponible a partir de PHP 7.2.0 y PECL zip 1.14.0, respectivamente, si se compila con libzip ≥ 1.2.0.
ZipArchive::EM_AES_128(integer)
Encriptación AES 128. Disponible a partir de PHP 7.2.0 y PECL zip 1.14.0, respectivamente, si se compila con libzip ≥ 1.2.0.
ZipArchive::EM_AES_192(integer)
Encriptación AES 192. Disponible a partir de PHP 7.2.0 y PECL zip 1.14.0, respectivamente, si se compila con libzip ≥ 1.2.0.
ZipArchive::EM_AES_256(integer)
Encriptación AES 256. Disponible a partir de PHP 7.2.0 y PECL zip 1.14.0, respectivamente, si se compila con libzip ≥ 1.2.0.
ZipArchive::LIBZIP_VERSION(string)
Versión de la biblioteca Zip. Disponible a partir de PHP 7.4.3 y PECL zip 1.16.0.
Constantes de sistema operativo para atributos externos
ZipArchive::OPSYS_DOS(integer)
ZipArchive::OPSYS_AMIGA(integer)
ZipArchive::OPSYS_OPENVMS(integer)
ZipArchive::OPSYS_UNIX(integer)
ZipArchive::OPSYS_VM_CMS(integer)
ZipArchive::OPSYS_ATARI_ST(integer)
ZipArchive::OPSYS_OS_2(integer)
ZipArchive::OPSYS_MACINTOSH(integer)
ZipArchive::OPSYS_Z_SYSTEM(integer)
ZipArchive::OPSYS_CPM(integer)
ZipArchive::OPSYS_WINDOWS_NTFS(integer)
ZipArchive::OPSYS_MVS(integer)
ZipArchive::OPSYS_VSE(integer)
ZipArchive::OPSYS_ACORN_RISC(integer)
ZipArchive::OPSYS_VFAT(integer)
ZipArchive::OPSYS_ALTERNATE_MVS(integer)
ZipArchive::OPSYS_BEOS(integer)
ZipArchive::OPSYS_TANDEM(integer)
ZipArchive::OPSYS_OS_400(integer)
ZipArchive::OPSYS_OS_X(integer)
ZipArchive::OPSYS_DEFAULT(integer)
Desde PHP 5.6.0, PECL zip 1.12.4


Ejemplos

Ejemplo #1 Crear un fichero Zip

<?php

$zip
= newZipArchive();
$filename="./test112.zip";

if (
$zip->open($filename,ZipArchive::CREATE)!==TRUE) {
exit(
"cannot open <$filename>\n");
}

$zip->addFromString("testfilephp.txt".time(),"#1 Esto es una cadena de prueba añadida como testfilephp.txt.\n");
$zip->addFromString("testfilephp2.txt".time(),"#2 Esto es una cadena de prueba añadida como testfilephp2.txt.\n");
$zip->addFile($thisdir."/too.php","/testfromfile.php");
echo
"numficheros: ".$zip->numFiles."\n";
echo
"estado:".$zip->status."\n";
$zip->close();
?>

Ejemplo #2 Volcar la información del archivo y listarlos

<?php
$za
= newZipArchive();

$za->open('test_with_comment.zip');
print_r($za);
var_dump($za);
echo
"numFicheros: ".$za->numFiles."\n";
echo
"estado: ".$za->status."\n";
echo
"estadosSis: ".$za->statusSys."\n";
echo
"nombreFichero: ".$za->filename."\n";
echo
"comentario: ".$za->comment."\n";

for (
$i=0;$i<$za->numFiles;$i++) {
echo
"index:$i\n";
print_r($za->statIndex($i));
}
echo
"numFichero:".$za->numFiles."\n";
?>

Ejemplo #3 Usando contenedor Zip, leer meta info de OpenOffice

<?php
$reader
= newXMLReader();

$reader->open('zip://'.dirname(__FILE__) .'/test.odt#meta.xml');
$odt_meta= array();
while (
$reader->read()) {
if (
$reader->nodeType==XMLREADER::ELEMENT) {
$elm=$reader->name;
} else {
if (
$reader->nodeType==XMLREADER::END_ELEMENT&&$reader->name=='office:meta') {
break;
}
if (!
trim($reader->value)) {
continue;
}
$odt_meta[$elm] =$reader->value;
}
}
print_r($odt_meta);
?>

Este ejemplo utiliza la antigua API (PHP 4), abre un fichero ZIP, lee cada fichero del archivo y imprime su contenido. El archivotest2.zipusado en este ejmplo es uno de los archivos de prueba la fuente de distribución de ZZIPlib.

Ejemplo #4 Ejemplo del uso de Zip

<?php

$zip
=zip_open("/tmp/test2.zip");

if (
$zip) {
while (
$zip_entry=zip_read($zip)) {
echo
"Nombre: ".zip_entry_name($zip_entry) ."\n";
echo
"Tamaño actual del fichero: ".zip_entry_filesize($zip_entry) ."\n";
echo
"Tamaño comprimido: ".zip_entry_compressedsize($zip_entry) ."\n";
echo
"Método de compresión: ".zip_entry_compressionmethod($zip_entry) ."\n";

if (
zip_entry_open($zip,$zip_entry,"r")) {
echo
"Contenido del fichero:\n";
$buf=zip_entry_read($zip_entry,zip_entry_filesize($zip_entry));
echo
"$buf\n";

zip_entry_close($zip_entry);
}
echo
"\n";

}

zip_close($zip);

}
?>


TheZipArchiveclass

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

Introducción

Un fichero, comprimido con Zip.

Sinopsis de la Clase

classZipArchive{
/* Propiedades */
string$filename;
string$comment;
/* Métodos */
addEmptyDir(string$dirname):bool
publicaddFile(
    string$filepath,
    string$entryname= "",
    int$start= 0,
    int$length= 0,
    int$flags= ZipArchive::FL_OVERWRITE
):bool
addFromString(string$localname,string$contents):bool
addGlob(string$pattern,int$flags= 0,array$options= array()):bool
addPattern(string$pattern,string$path= ".",array$options= array()):array
publicclearError():void
close():bool
publiccount():int
deleteIndex(int$index):bool
deleteName(string$name):bool
extractTo(string$destination,mixed$entries= ?):bool
getArchiveComment(int$flags= ?):string
getCommentIndex(int$index,int$flags= ?):string
getCommentName(string$name,int$flags= ?):string
GetExternalAttributesIndex(
    int$index,
    int&$opsys,
    int&$attr,
    int$flags= ?
):bool
getExternalAttributesName(
    string$name,
    int&$opsys,
    int&$attr,
    int$flags= ?
):bool
getFromIndex(int$index,int$length= 0,int$flags= ?):string
getFromName(string$name,int$length= 0,int$flags= ?):string
getNameIndex(int$index,int$flags= ?):string
getStream(string$name):resource
publicgetStreamIndex(int$index,int$flags= 0):resource|false
publicgetStreamName(string$name,int$flags= 0):resource|false
publicstaticisCompressionMethodSupported(int$method,bool$enc=true):bool
publicstaticisEncryptionMethodSupported(int$method,bool$enc=true):bool
locateName(string$name,int$flags= ?):int
open(string$filename,int$flags= ?):mixed
registerProgressCallback(float$rate,callable$callback):bool
renameIndex(int$index,string$newname):bool
renameName(string$name,string$newname):bool
replaceFile(
    string$filename,
    int$index,
    int$start= 0,
    int$length= 0,
    int$flags= 0
):bool
setArchiveComment(string$comment):bool
setCommentIndex(int$index,string$comment):bool
setCommentName(string$name,string$comment):bool
setCompressionIndex(int$index,int$comp_method,int$comp_flags= 0):bool
setCompressionName(string$name,int$comp_method,int$comp_flags= 0):bool
setEncryptionIndex(int$index,string$method,string$password= ?):bool
setEncryptionName(string$name,int$method,string$password= ?):bool
setExternalAttributesIndex(
    int$index,
    int$opsys,
    int$attr,
    int$flags= ?
):bool
setExternalAttributesName(
    string$name,
    int$opsys,
    int$attr,
    int$flags= ?
):bool
setMtimeIndex(int$index,int$timestamp,int$flags= ?):bool
setMtimeName(string$name,int$timestamp,int$flags= ?):bool
publicsetPassword(string$password):bool
statIndex(int$index,int$flags= ?):array
statName(string$name,int$flags= ?):array
unchangeIndex(int$index):bool
unchangeName(string$name):bool
}

Propiedades

status

Estado del archivo Zip

statusSys

Estado del sistema del archivo Zip

numFiles

Número de ficheros en el archivo

filename

Nombre del archivo en le sistema de archivos

comment

Comentario para el archivo


ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDirAñadir un nuevo directorio

Descripción

ZipArchive::addEmptyDir(string$dirname):bool

Añade un directoro vacío en el archivo.

Parámetros

dirname

El directorio a añadir.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Crea un nuevo directorio en un archivo

<?php
$zip
= newZipArchive;
if (
$zip->open('test.zip') ===TRUE) {
if(
$zip->addEmptyDir('newDirectory')) {
echo
'Creado nuevo directorio root';
} else {
echo
'No se puede crear el directorio';
}
$zip->close();
} else {
echo
'falló';
}
?>


ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFileAñade un fichero al archivo ZIP para la ruta dada

Descripción

publicZipArchive::addFile(
    string$filepath,
    string$entryname= "",
    int$start= 0,
    int$length= 0,
    int$flags= ZipArchive::FL_OVERWRITE
):bool

Añade un fichero al archivo ZIP par la ruta dada.

Nota:Para una portabilidad máxima, se recomienda utilizar siempre barras hacia adelante (/) como separador de directorios en nombres de ficheros ZIP.

Parámetros

filename

La ruta del fichero a añadir.

entryname

Si corresponde, este es el nombre local dentro del archivo ZIP que reemplazará elfilepath.

start

Para la copia parcial, posición de inicio.

length

Para la copia parcial, longitud a copiar, si es 0 o -1 se utiliza todo el fichero (empezando porstart).

flags

Máscara de bits compuesta porZipArchive::FL_OVERWRITE,ZipArchive::FL_ENC_GUESS,ZipArchive::FL_ENC_UTF_8,ZipArchive::FL_ENC_CP437. El comportamiento de estas constantes se describe en lapágina de constantes ZIP.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Historial de cambios

VersiónDescripción
8.0.0 / 1.18.0Se añadioflags.

Ejemplos

Este ejemplo abre un archivo ZIPtest.zipy añade el fichero/path/to/index.txt. comonewname.txt.

Ejemplo #1 Abrir y extraer

<?php
$zip
= newZipArchive;
if (
$zip->open('test.zip') ===TRUE) {
$zip->addFile('/path/to/index.txt','newname.txt');
$zip->close();
echo
'ok';
} else {
echo
'failed';
}
?>

Notas

Nota:

Cuando un fichero es añadido al archivo, PHP bloqueará el fichero. El bloqueo se desbloqueará cuando el objetoZipArchivefinalice, ya sea a través deZipArchive::close()o el objetoZipArchivesea destruido. Esto puede impedir que se pueda eliminar el archivo que se está añadiendo hasta después de que el bloqueo haya sido liberado.

Ver también



ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromStringAñadir un fichero al archivo ZIP usando su contenido

Descripción

ZipArchive::addFromString(string$localname,string$contents):bool

Añade un fichero al archivo ZIP usando su contenido.

Parámetros

localname

Nombre de la entrada a crear.

contents

El contenido a usar para crear la entrada. Es usado en modo binary safe.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Añade una entrada al nuevo fichero

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if (
$res===TRUE) {
$zip->addFromString('test.txt','el contenido del fichero va aquí');
$zip->close();
echo
'ok';
} else {
echo
'failed';
}
?>

Ejemplo #2 Añade un fichero en un directorio dentro de un archivo

<?php
$zip
= newZipArchive;
if (
$zip->open('test.zip') ===TRUE) {
$zip->addFromString('dir/test.txt','el contenido del fichero va aquí');
$zip->close();
echo
'ok';
} else {
echo
'falló';
}
?>


ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlobAñadir ficheros de un directorio mediante un patrón glob

Descripción

ZipArchive::addGlob(string$pattern,int$flags= 0,array$options= array()):bool

Añade ficheros de un directorio que corresponde con el patrón globalpattern.

Parámetros

pattern

Un patrónglob()contra el cual se hará la correspondencia con los ficheros.

flags

Una máscara de un bit de marcasglob().

options

Un array asociativo de opciones. Las opciones disponibles son:

  • "add_path"

    Prefijo a indicar cuando se traduce la ruta de acceso del fichero dentro del archivo. Esta traducción se aplica después de cualquier operación de eliminación definida por las opciones"remove_path"o"remove_all_path".

  • "remove_path"

    Prefijo para eliminar la ruta de acceso de los ficheros antes de añadirlos al archivo.

  • "remove_all_path"

    truepara utilizar únicamente el nombre del fichero y añadirlo a la raíz del archivo.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo conZipArchive::addGlob()

Añadir todos los ficheros de scripts y texto php del directorio de trabajo actual

<?php
$zip
= newZipArchive();
$ret=$zip->open('application.zip',ZipArchive::OVERWRITE);
if (
$ret!==TRUE) {
printf('Erróneo con el código %d',$ret);
} else {
$options= array('add_path'=>'sources/','remove_all_path'=>TRUE);
$zip->addGlob('*.{php,txt}',GLOB_BRACE,$options);
$zip->close();
}
?>

Ver también



ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPatternAñade ficheros de un directorio a partir de un patrón PCRE

Descripción

ZipArchive::addPattern(string$pattern,string$path= ".",array$options= array()):array

Añade ficheros de un directorio que coinciden con la expresión regularpattern. La operación no es recursiva. Únicamente se hará la correspondencia del patrón con el nombre del fichero.

Parámetros

pattern

Un patrónPCREcontra el cual se realizará la correspondencia.

path

El directorio que será escaneado. Por defecto es el directorio de trabajo actual.

options

Un array asociativo de opciones aceptadas porZipArchive::addGlob().

Valores devueltos

Unarrayde archivos añadidos en caso de éxito ofalseen caso de error

Ejemplos

Ejemplo #1 Ejemplo conZipArchive::addPattern()

Añadir todos los scripts y ficheros de texto php del directorio actual

<?php
$zip
= newZipArchive();
$ret=$zip->open('application.zip',ZipArchive::CREATE|ZipArchive::OVERWRITE);
if (
$ret!==TRUE) {
printf('Erróneo con código %d',$ret);
} else {
$directory=realpath('.');
$options= array('add_path'=>'sources/','remove_path'=>$directory);
$zip->addPattern('/\.(?:php|txt)$/',$directory,$options);
$zip->close();
}
?>

Ver también



ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearErrorClear the status error message, system and/or zip messages

Descripción

publicZipArchive::clearError():void

Clear the status error message, system and/or zip messages.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

No devuelve ningún valor.

Ver también



ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::closeCierra el fichero activo (abierto o el nuevo creado)

Descripción

ZipArchive::close():bool

Cierra fichero abierto o creado y guarda los cambios. Este método es automáticamente llamado al finalizar el script.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::countCuenta el número de archivos en el archivo

Descripción

publicZipArchive::count():int

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el número de ficheros en el archivo.



ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndexElimina una entrada en el archivo usando su índice

Descripción

ZipArchive::deleteIndex(int$index):bool

Elimina una entrada en su archivo usando su índice.

Parámetros

index

Índice de la entrada a eliminar.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Elimina el fichero desde el archivo usando su índice

<?php
$zip
= newZipArchive;
if (
$zip->open('test.zip') ===TRUE) {
$zip->deleteIndex(2);
$zip->close();
echo
'ok';
} else {
echo
'falló';
}
?>


ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteNameElimina una entrada en el archivo por su nombre

Descripción

ZipArchive::deleteName(string$name):bool

Elimina una entrada en el archivo por su nombre

Parámetros

name

Nombre de la entrada a eliminar.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Eliminado un fichero y un directorio desde un archivo, usando nombres

<?php
$zip
= newZipArchive;
if (
$zip->open('test1.zip') ===TRUE) {
$zip->deleteName('testfromfile.php');
$zip->deleteName('testDir/');
$zip->close();
echo
'ok';
} else {
echo
'Falló';
}
?>


ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractToExtraer el contenido del archivo

Descripción

ZipArchive::extractTo(string$destination,mixed$entries= ?):bool

Extrae el archivo completo o los ficheros dados en la ruta que se especifique.

Advertencia

Los permisos por omisión para los archivos y directorios extraídos dan el más amplio acceso posible. Esto se puede restringir estableciendo la umask actual, que se puede cambiar usandoumask().

Parámetros

destination

Destino en donde extraer los ficheros.

entries

Las entradas a extraer. Acepta tanto un solo nombre o un array de nombres.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Extraer todas las entradas

<?php
$zip
= newZipArchive;
if (
$zip->open('test.zip') ===TRUE) {
$zip->extractTo('/my/destination/dir/');
$zip->close();
echo
'ok';
} else {
echo
'failed';
}
?>

Ejemplo #2 Extraer dos entradas

<?php
$zip
= newZipArchive;
$res=$zip->open('test_im.zip');
if (
$res===TRUE) {
$zip->extractTo('/my/destination/dir/', array('pear_item.gif','testfromfile.php'));
$zip->close();
echo
'ok';
} else {
echo
'failed';
}
?>


ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveCommentDevuelve el comentario del archivo ZIP

Descripción

ZipArchive::getArchiveComment(int$flags= ?):string

Devuelve el comentario del archivo ZIP.

Parámetros

flags

Si las flags se establecen enZipArchive::FL_UNCHANGED, el comentario original se devuelve sin cambios.

Valores devueltos

Devuelve el comentario del archivo Zip ofalseen caso de error.

Ejemplos

Ejemplo #1 Vuelca el comentario del archivo

<?php
$zip
= newZipArchive;
$res=$zip->open('test_with_comment.zip');
if (
$res===TRUE) {
var_dump($zip->getArchiveComment());
/* O usando la propiedad del archivo */
var_dump($zip->comment);
} else {
echo
'falló, código:'.$res;
}
?>


ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndexDevuelve el comentario de una entrada usando la entrada díndice

Descripción

ZipArchive::getCommentIndex(int$index,int$flags= ?):string

Devuelve el comentario de una entrada usando la entrada índice.

Parámetros

index

Índice de la entrada

flags

Si flagsZipArchive::FL_UNCHANGED, se devolverá el comentario original no cambiado.

Valores devueltos

Con éxito devuelve el comentario ofalseen caso de error.

Ejemplos

Ejemplo #1 Vuelca el comentario de la entrada

<?php
$zip
= newZipArchive;
$res=$zip->open('test1.zip');
if (
$res===TRUE) {
var_dump($zip->getCommentIndex(1));
} else {
echo
'falló, código:'.$res;
}
?>


ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentNameDevuelve el comentario de una entrada usando el nombre de la entrada

Descripción

ZipArchive::getCommentName(string$name,int$flags= ?):string

Devuelve el comentario de una entrada usando el nombre de la entrada.

Parámetros

name

Nombre de la entrada

flags

Si flags está defindo aZipArchive::FL_UNCHANGED, se devuelve el comentario original no cambiado.

Valores devueltos

Devuelve el comentario si se ejecutó con éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Vuelca el comentario de la entrada

<?php
$zip
= newZipArchive;
$res=$zip->open('test1.zip');
if (
$res===TRUE) {
var_dump($zip->getCommentName('test/entry1.txt'));
} else {
echo
'Falló, código:'.$res;
}
?>


ZipArchive::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndexObtener los atributos externos de una entrada definida por su índice

Descripción

ZipArchive::GetExternalAttributesIndex(
    int$index,
    int&$opsys,
    int&$attr,
    int$flags= ?
):bool

Recuperar los atributos externos de una entrada definida por su índice.

Parámetros

index

El índice de la entrada.

opsys

En caso de éxito, recibe el código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.

attr

En caso de éxito, recibe los atributos externos. El valor dependerá del sistema operativo.

flags

Si flags se establece aZipArchive::FL_UNCHANGED, se devuelven los atributos originales sin cambios.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Este ejemplo extrae todas las entradas de un archivo ZIPtest.zipy asigna los permisos Unix tomados de los atributos externos.

Ejemplo #1 Extraer todas las entradas con permisos Unix

<?php
$zip
= newZipArchive();
if (
$zip->open('test.zip') ===TRUE) {
for (
$idx=0;$s=$zip->statIndex($idx) ;$idx++) {
if (
$zip->extractTo('.',$s['name'])) {
if (
$zip->getExternalAttributesIndex($idx,$opsys,$attr)
&&
$opsys==ZipArchive::OPSYS_UNIX) {
chmod($s['name'], ($attr>>16) &0777);
}
}
}
$zip->close();
echo
"Ok\n";
} else {
echo
"KO\n";
}
?>


ZipArchive::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesNameObtener los atributos externos de una entrada definida por su nombre

Descripción

ZipArchive::getExternalAttributesName(
    string$name,
    int&$opsys,
    int&$attr,
    int$flags= ?
):bool

Obtener los atributos externos de una entrada definida por su nombre.

Parámetros

name

El nombre de la entrada.

opsys

En caso de éxito, recibe el código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.

attr

En caso de éxito, recibe los atributos externos. El valor depende del sistema operativo.

flags

Si flags se establece aZipArchive::FL_UNCHANGED, se devuelven los atributos originales sin cambios.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndexDevuelve el contenido de la entrada usando su índice

Descripción

ZipArchive::getFromIndex(int$index,int$length= 0,int$flags= ?):string

Devuelve el contenido de la entrada usando su índice.

Parámetros

index

El índice de la entrada

length

La longitud que se see desde la entrada. Si es0, entonces toda la entrada se lee.

flags

Las flags usadas para abrir el fichero. Los siguientes valores pueden ser Ored.

  • ZipArchive::FL_UNCHANGED

  • ZipArchive::FL_COMPRESSED

Valores devueltos

Devuelve el contenido de la entrada si se ejecutó con éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Obtener el contenido del fichero

<?php
$zip
= newZipArchive;
if (
$zip->open('test.zip') ===TRUE) {
echo
$zip->getFromIndex(2);
$zip->close();
} else {
echo
'falló';
}
?>

Ver también



ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromNameDevuelve el contenido de la entrada utilizando su nombre

Descripción

ZipArchive::getFromName(string$name,int$length= 0,int$flags= ?):string

Devuelve el contenido de la entrada utilizando su nombre

Parámetros

name

Nombre de la entrada

length

La longitud a ser leída desde la entrada. Si es0, entonces toda la entrada es leída.

flags

Los indicadores a utilizar para abrir el archivo. Los siguientes valores podrían ser escritos juntos con un OR lógico en él.

  • ZipArchive::FL_UNCHANGED

  • ZipArchive::FL_COMPRESSED

  • ZipArchive::FL_NOCASE

Valores devueltos

Devuelve el contenido de la entrada en caso de tener éxito, ofalseen caso de error.

Ejemplos

Ejemplo #1 Obtener el contenido de los ficheros

<?php
$zip
= newZipArchive;
if (
$zip->open('test1.zip') ===TRUE) {
echo
$zip->getFromName('testfromfile.php');
$zip->close();
} else {
echo
'falló';
}
?>

Ejemplo #2 Convierte una imagen desde una entrada de fichero zip

<?php
$z
= newZipArchive();
if (
$z->open(dirname(__FILE__) .'/test_im.zip')) {
$im_string=$z->getFromName("pear_item.gif");
$im=imagecreatefromstring($im_string);
imagepng($im,'b.png');
}
?>

Ver también



ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndexDevuelve el nombre de una entrada utilizando su índice

Descripción

ZipArchive::getNameIndex(int$index,int$flags= ?):string

Devuelve el nombre de una entrada utilizando su índice.

Parámetros

index

El índice de la entrada.

flags

Si las flags se establecen enZipArchive::FL_UNCHANGED, el nombre original es devuelto sin cambios.

Valores devueltos

Devuelve el nombre en caso de tener éxito, ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo deZipArchive::getNameIndex()

<?php
if ($zip->open('test.zip') ==TRUE) {
for (
$i=0;$i<$zip->numFiles;$i++) {
$filename=$zip->getNameIndex($i);
// ...
}
}
?>



ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusStringDevuelve mensajes de: estado de error, de sistema y/o mensajes de zip

Descripción

ZipArchive::getStatusString():string

Devuelve mensajes de: estado de error, de sistema y/o mensajes de zip.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve unstringcon el mensaje de estado en caso de tener éxito, ofalseen caso de error.

Historial de cambios

VersiónDescripción
8.0.0 / 1.18.0Este método puede ser llamado en un archivo cerrado.



ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStreamObtener un manejador de fichero para la entrada definido por su nombre (sólo lectura)

Descripción

ZipArchive::getStream(string$name):resource

Obtener un manejador de fichero para la entrada definido por su nombre. Por ahora, éste solamente soporta operaciones de lectura.

Parámetros

name

El nombre de la entrada a utilizar.

Valores devueltos

Devuelve un puntero de fichero (un recurso) en caso de tener éxito, ofalseen caso de error.

Ejemplos

Ejemplo #1 Obtiene los contenidos de entrada confread()y lo almacena

<?php
$contents
='';
$z= newZipArchive();
if (
$z->open('test.zip')) {
$fp=$z->getStream('test');
if(!
$fp) exit("failed\n");

while (!
feof($fp)) {
$contents.=fread($fp,2);
}

fclose($fp);
file_put_contents('t',$contents);
echo
"done.\n";
}
?>

Ejemplo #2 Lo mismo como el ejemplo anterior pero confopen()y el envoltorio de flujo de zip

<?php
$contents
='';
$fp=fopen('zip://'.dirname(__FILE__) .'/test.zip#test','r');
if (!
$fp) {
exit(
"cannot open\n");
}
while (!
feof($fp)) {
$contents.=fread($fp,2);
}
echo
"$contents\n";
fclose($fp);
echo
"done.\n";
?>

Ejemplo #3 El flujo de envoltorio y la imagen, también pueden ser utilizados con la función xml

<?php
$im
=imagecreatefromgif('zip://'.dirname(__FILE__) .'/test_im.zip#pear_item.gif');
imagepng($im,'a.png');
?>


ZipArchive::getStreamIndex

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamIndexGet a file handler to the entry defined by its index (read only)

Descripción

publicZipArchive::getStreamIndex(int$index,int$flags= 0):resource|false

Get a file handler to the entry defined by its index. For now, it only supports read operations.

Parámetros

index

Index of the entry

flags

If flags is set toZipArchive::FL_UNCHANGED, the original unchanged stream is returned.

Valores devueltos

Returns a file pointer (resource) on success ofalseen caso de error.

Ejemplos

Ejemplo #1 Get the entry contents withfread()and store it

<?php
$contents
='';
$z= newZipArchive();
if (
$z->open('test.zip')) {
$fp=$z->getStreamIndex(1,ZipArchive::FL_UNCHANGED);
if(!
$fp) die($z->getStatusString());

echo
stream_get_contents($fp);

fclose($fp);
}
?>

Ver también



ZipArchive::getStreamName

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamNameGet a file handler to the entry defined by its name (read only)

Descripción

publicZipArchive::getStreamName(string$name,int$flags= 0):resource|false

Get a file handler to the entry defined by its name. For now, it only supports read operations.

Parámetros

name

The name of the entry to use.

flags

If flags is set toZipArchive::FL_UNCHANGED, the original unchanged stream is returned.

Valores devueltos

Returns a file pointer (resource) on success ofalseen caso de error.

Ejemplos

Ejemplo #1 Get the entry contents withfread()and store it

<?php
$contents
='';
$z= newZipArchive();
if (
$z->open('test.zip')) {
$fp=$z->getStreamName('test',ZipArchive::FL_UNCHANGED);
if(!
$fp) die($z->getStatusString());

echo
stream_get_contents($fp);

fclose($fp);
}
?>

Ver también



ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupportedCheck if a compression method is supported by libzip

Descripción

publicstaticZipArchive::isCompressionMethodSupported(int$method,bool$enc=true):bool

Check if a compression method is supported by libzip.

Parámetros

method

The compression method, one of theZipArchive::CM_*constants.

enc

Iftruecheck for compression, else check for decompression.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Notas

Nota:

This function is only available if built against libzip ≥ 1.7.0.

Ver también



ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupportedCheck if a encryption method is supported by libzip

Descripción

publicstaticZipArchive::isEncryptionMethodSupported(int$method,bool$enc=true):bool

Check if a compression method is supported by libzip.

Parámetros

method

The encryption method, one of theZipArchive::EM_*constants.

enc

Iftruecheck for encryption, else check for decryption.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Notas

Nota:

This function is only available if built against libzip ≥ 1.7.0.

Ver también



ZipArchive::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateNameDevuelve el índice de la entrada en el archivo

Descripción

ZipArchive::locateName(string$name,int$flags= ?):int

Localiza una entrada utilizando su nombre.

Parámetros

name

El nombre de la entrada a buscar

flags

Los indicadores son especificados agregándoles OR a los siguientes valores, ó 0 para ninguno de ellos.

  • ZipArchive::FL_NOCASE

  • ZipArchive::FL_NODIR

Valores devueltos

Devuelve el índice de la entrada en caso de tener éxito, ofalseen caso de error.

Ejemplos

Ejemplo #1 Crear un archivo y luego utilizarlo conZipArchive::locateName()

<?php
$file
='testlocate.zip';

$zip= newZipArchive;
if (
$zip->open($file,ZipArchive::CREATE) !==TRUE) {
exit(
'falló');
}

$zip->addFromString('entry1.txt','entry #1');
$zip->addFromString('entry2.txt','entry #2');
$zip->addFromString('dir/entry2d.txt','entry #2');

if (!
$zip->status==ZipArchive::ER_OK) {
echo
"falló al escribir en el archivo zip\n";
}
$zip->close();

if (
$zip->open($file) !==TRUE) {
exit(
'falló');
}

echo
$zip->locateName('entry1.txt') ."\n";
echo
$zip->locateName('eNtry2.txt') ."\n";
echo
$zip->locateName('eNtry2.txt',ZipArchive::FL_NOCASE) ."\n";
echo
$zip->locateName('enTRy2d.txt',ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) ."\n";
$zip->close();

?>

El resultado del ejemplo sería:

El ejemplo de arriba mostrará la salida:

0

1
2


ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::openAbrir un fichero de archivo en formato ZIP

Descripción

ZipArchive::open(string$filename,int$flags= ?):mixed

Abre un archivo zip nuevo o existente para leer, escribir o modificar.

Desde libzip 1.6.0, un archivo vacío ya no es un archivo válido.

Parámetros

filename

El nombre del fichero del archivo ZIP para ser abierto.

flags

El modo a utilizar para abrir el archivo.

Valores devueltos

Error codes

Devuelvetrueen caso de éxito o el código de error.

  • ZipArchive::ER_EXISTS

    El fichero ya existe.

  • ZipArchive::ER_INCONS

    Archivo zip inconsistente.

  • ZipArchive::ER_INVAL

    Argumento no válido.

  • ZipArchive::ER_MEMORY

    Falló malloc.

  • ZipArchive::ER_NOENT

    No existe el fichero.

  • ZipArchive::ER_NOZIP

    No es un archivo zip.

  • ZipArchive::ER_OPEN

    No se puede abrir el fichero.

  • ZipArchive::ER_READ

    Error de lectura.

  • ZipArchive::ER_SEEK

    Error de búsqueda.

Ejemplos

Ejemplo #1 Abrir y extraer

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip');
if (
$res===TRUE) {
echo
'ok';
$zip->extractTo('test');
$zip->close();
} else {
echo
'falló, código:'.$res;
}
?>

Ejemplo #2 Crear un fichero

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if (
$res===TRUE) {
$zip->addFromString('test.txt','el contenido del fichero va aquí');
$zip->addFile('data.txt','entryname.txt');
$zip->close();
echo
'ok';
} else {
echo
'falló';
}
?>

Ejemplo #3 Crear un fichero temporal

<?php
$name
=tempnam(sys_get_temp_dir(),"FOO");
$zip= newZipArchive;
$res=$zip->open($name,ZipArchive::OVERWRITE);/* truncate as empty file is not valid */
if ($res===TRUE) {
$zip->addFile('data.txt','entryname.txt');
$zip->close();
echo
'ok';
} else {
echo
'failed';
}
?>


ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallbackRegistrar una llamada para permitir la cancelación durante el cierre del archivo

Descripción

ZipArchive::registerCancelCallback(callable$callback):bool

Registrar una funcióncallbackpara permitir la cancelación durante el cierre del archivo.

Parámetros

callback

Si esta función vuelve a 0, la operación continuará, otro valor será cancelado.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Notas

Nota:

Esta función sólo está disponible si se construye con libzip ≥ 1.6.0.

Ejemplos

Este ejemplo crea un archivo ZIPphp.zipy cancela la operación en alguna condición de operación.

Ejemplo #1 Archive a file

<?php
$zip
= newZipArchive();
if (
$zip->open('php.zip',ZipArchive::CREATE|ZipArchive::OVERWRITE)) {
$zip->addFile(PHP_BINARY,'php');
$zip->registerCancelCallback(function () {
return (
$someruncondition? -1:0);
});
$zip->close();
}

Ver también



ZipArchive::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallbackRegistra una llamada para proporcionar actualizaciones durante el cierre del archivo

Descripción

ZipArchive::registerProgressCallback(float$rate,callable$callback):bool

Registra una funcióncallbackpara proporcionar actualizaciones durante el cierre del archivo.

Parámetros

rate

Cambiar entre cada llamada de la devolución de llamada (de 0.0 a 1.0).

callback

Esta función recibirá el actualstatecomo unfloat(de 0.0 a 1.0).

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Notas

Nota:

Esta función sólo está disponible si se construye con libzip ≥ 1.3.0.

Ejemplos

Este ejemplo crea un archivo ZIPphp.zipy muestra la progresión.

Ejemplo #1 Archive a file

$zip = new ZipArchive();
if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
$zip->addFile(PHP_BINARY, 'php');
$zip->registerProgressCallback(0.05, function ($r) {
printf("%d%%\n", $r * 100);
});
$zip->close();
}

Ver también



ZipArchive::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndexRenombra una entrada definida por su índice

Descripción

ZipArchive::renameIndex(int$index,string$newname):bool

Renombra una entrada definida por su índice.

Parámetros

index

Índice de la entrada a renombrar.

newname

Nombre nuevo.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Renombra una entrada

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip');
if (
$res===TRUE) {
$zip->renameIndex(2,'newname.txt');
$zip->close();
} else {
echo
'falló, código:'.$res;
}
?>


ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameNameRenombra una entrada definida por su nombre

Descripción

ZipArchive::renameName(string$name,string$newname):bool

Renombra una entrada definida por su nombre.

Parámetros

name

Nombre de la entrada a renombrar.

newname

Nombre nuevo.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Renombra una entrada

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip');
if (
$res===TRUE) {
$zip->renameName('currentname.txt','newname.txt');
$zip->close();
} else {
echo
'falló, código:'.$res;
}
?>


ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFileReemplaza fichero en el archivo ZIP con una ruta determinada

Descripción

ZipArchive::replaceFile(
    string$filename,
    int$index,
    int$start= 0,
    int$length= 0,
    int$flags= 0
):bool

Reemplaza fichero en el archivo ZIP con una ruta determinada.

Nota:Para una portabilidad máxima, se recomienda utilizar siempre barras hacia adelante (/) como separador de directorios en nombres de ficheros ZIP.

Parámetros

filename

La ruta del archivo a añadir.

index

El índice del archivo a reemplazar, su nombre no ha cambiado.

start

Para la copia parcial, posición de inicio.

length

Para la copia parcial, la longitud a copiar, si 0 o -1 el archivo completo es usado (a partir destart).

flags

La máscara de bits consiste enZipArchive::FL_ENC_GUESS,ZipArchive::FL_ENC_UTF_8,ZipArchive::FL_ENC_CP437. El comportamiento de estas constantes se describe en la páginaconstantes ZIP.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Este ejemplo abre un archivo ZIPtest.zipy sustituye la entrada del índice 1 con/path/to/index.txt.

Ejemplo #1 Abrir y reemplazar

<?php
$zip
= newZipArchive;
if (
$zip->open('test.zip') ===TRUE) {
$zip->replaceFile('/path/to/index.txt',1);
$zip->close();
echo
'ok';
} else {
echo
'failed';
}
?>

Ver también



ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveCommentEstablece el comentario de un archivo ZIP

Descripción

ZipArchive::setArchiveComment(string$comment):bool

Establece el comentario de un archivo ZIP.

Parámetros

comment

Los contenidos del comentario.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Crear un archivo y establecer un comentario

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if (
$res===TRUE) {
$zip->addFromString('test.txt','El contenido del fichero va aquí');
$zip->setArchiveComment('nuevo comentario del archivo');
$zip->close();
echo
'ok';
} else {
echo
'falló';
}
?>


ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndexEstablece el comentario de una entrada definido por su índice

Descripción

ZipArchive::setCommentIndex(int$index,string$comment):bool

Establece el comentario de una entrada definido por su índice.

Parámetros

index

Índice de la entrada.

comment

Los contenidos del comentario.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Abrir un archivo y establecer un comentario para una entrada

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip');
if (
$res===TRUE) {
$zip->setCommentIndex(2,'comentario de la entrada nueva');
$zip->close();
echo
'ok';
} else {
echo
'falló';
}
?>


ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentNameEstablece el comentario de una entrada definido por su nombre

Descripción

ZipArchive::setCommentName(string$name,string$comment):bool

Establece el comentario de una entrada definido por su nombre.

Parámetros

name

Nombre de la entrada.

comment

Los contenidos del comentario.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Abrir un archivo y establecer un comentario para una entrada

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip');
if (
$res===TRUE) {
$zip->setCommentName('entry1.txt','comentario de la entrada nueva');
$zip->close();
echo
'ok';
} else {
echo
'falló';
}
?>


ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndexEstablecer el método de compresión de una entrada definida por su índice

Descripción

ZipArchive::setCompressionIndex(int$index,int$comp_method,int$comp_flags= 0):bool

Establecer el método de compresión de una entrada definida por su índice.

Parámetros

index

El índice de la entrada.

comp_method

El método de compresión, una de las constantesZipArchive::CM_*.

comp_flags

Nivel de compresión.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Añadir ficheros con diferentes métodos de compresión a un archivo

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if (
$res===TRUE) {
$zip->addFromString('foo','Un texto');
$zip->addFromString('bar','Otro texto');
$zip->setCompressionIndex(0,ZipArchive::CM_STORE);
$zip->setCompressionIndex(1,ZipArchive::CM_DEFLATE);
$zip->close();
echo
'ok';
} else {
echo
'fallo';
}
?>


ZipArchive::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionNameEstablecer el método de compresión de una entrada definida por su nombre

Descripción

ZipArchive::setCompressionName(string$name,int$comp_method,int$comp_flags= 0):bool

Establecer el método de compresión de una entrada definida por su nombre.

Parámetros

name

El nombre de la entrada.

comp_method

El método de compresión. Una de las constantesZipArchive::CM_*.

comp_flags

Nivel de compresión.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Añadir ficheros con diferentes métodos de compresión a un archivo

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if (
$res===TRUE) {
$zip->addFromString('foo','Un texto');
$zip->addFromString('bar','Otro texto');
$zip->setCompressionName('foo',ZipArchive::CM_STORE);
$zip->setCompressionName('bar',ZipArchive::CM_DEFLATE);
$zip->close();
echo
'ok';
} else {
echo
'fallo';
}
?>

Ejemplo #2 Añadir fichero y establecer el método de compresión

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip',ZipArchive::CREATE);
if (
$res===TRUE) {
$zip->addFile('foo.jpg','bar.jpg');
$zip->setCompressionName('bar.jpg',ZipArchive::CM_XZ);
$zip->close();
echo
'ok';
} else {
echo
'failed';
}
?>


ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndexEstablece el método de cifrado de una entrada definida por su índice

Descripción

ZipArchive::setEncryptionIndex(int$index,string$method,string$password= ?):bool

Establece el método de cifrado de una entrada definida por su índice.

Parámetros

index

Índice de la entrada.

method

El método de cifrado definido por una de las constantes ZipArchive::EM_ constants.

password

Contraseña opcional, se utiliza por defecto cuando falta.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Notas

Nota:

Esta función sólo está disponible si se construye con libzip ≥ 1.2.0.

Ver también



ZipArchive::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionNameEstablece el método de cifrado de una entrada definida por su nombre

Descripción

ZipArchive::setEncryptionName(string$name,int$method,string$password= ?):bool

Establece el método de cifrado de una entrada definida por su nombre.

Parámetros

name

Nombre de la entrada.

method

El método de encriptación definido por una de las constantes ZipArchive::EM_constants.

password

Contraseña opcional, se utiliza por defecto cuando falta.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Este ejemplo crea un archivo ZIPtest.zipy añade al archivotest.txtencriptado usando el método AES 256.

Ejemplo #1 Archivar y encriptar un archivo

<?php
$zip
= newZipArchive();
if (
$zip->open('test.zip',ZipArchive::CREATE) ===TRUE) {
$zip->setPassword('secret');
$zip->addFile('text.txt');
$zip->setEncryptionName('text.txt',ZipArchive::EM_AES_256);
$zip->close();
echo
"Ok\n";
} else {
echo
"KO\n";
}
?>

Notas

Nota:

Esta función sólo está disponible si se construye con libzip ≥ 1.2.0.

Ver también



ZipArchive::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndexEstablece los atributos externos de una entrada definida por su índice

Descripción

ZipArchive::setExternalAttributesIndex(
    int$index,
    int$opsys,
    int$attr,
    int$flags= ?
):bool

Establece los atributos externos de una entrada definida por su índice.

Parámetros

index

El índice de la entrada.

opsys

El código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.

attr

Los atributos externos. El valor depende del sistema operativo.

flags

Banderas opcionales. Actualmente no se utiliza.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesNameEstablece los atributos externos de una entrada definida por su nombre

Descripción

ZipArchive::setExternalAttributesName(
    string$name,
    int$opsys,
    int$attr,
    int$flags= ?
):bool

Establece los atributos externos de una entrada definida por su nombre.

Parámetros

name

El nombre de la entrada.

opsys

El código del sistema operativo definido por una de las constantes ZipArchive::OPSYS_.

attr

Los atributos externos. El valor depende del sistema operativo.

flags

Banderas opcionales. Actualmente no se utiliza.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Este ejemplo abre un archivo comprimido ZIPtest.zipy añade el ficherotest.txtcon sus permisos Unix como atributos externos.

Ejemplo #1 Archivar un fichero, con sus permisos Unix

<?php
$zip
= newZipArchive();
$stat=stat($filename='test.txt');
if (
is_array($stat) &&$zip->open('test.zip',ZipArchive::CREATE) ===TRUE) {
$zip->addFile($filename);
$zip->setExternalAttributesName($filename,ZipArchive::OPSYS_UNIX,$stat['mode'] <<16);
$zip->close();
echo
"Ok\n";
} else {
echo
"KO\n";
}
?>


ZipArchive::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndexEstablece el tiempo de modificación de una entrada definido por su índice

Descripción

ZipArchive::setMtimeIndex(int$index,int$timestamp,int$flags= ?):bool

Establece el tiempo de modificación de una entrada definido por su índice.

Parámetros

index

Índice de la entrada.

timestamp

La hora de modificación (unix timestamp) del archivo.

flags

Flags opcionales, sin usar por ahora.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Este ejemplo crea un archivo ZIPtest.zipy añade al archivotest.txtcon su fecha de modificación.

Ejemplo #1 Archivar un fichero

<?php
$zip
= newZipArchive();
if (
$zip->open('test.zip',ZipArchive::CREATE) ===TRUE) {
$zip->addFile('text.txt');
$zip->setMtimIndex(0,mktime(0,0,0,12,25,2019));
$zip->close();
echo
"Ok\n";
} else {
echo
"KO\n";
}
?>

Notas

Nota:

Esta función sólo está disponible si se construye con libzip ≥ 1.0.0.

Ver también



ZipArchive::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeNameEstablece la hora de modificación de una entrada definida por su nombre

Descripción

ZipArchive::setMtimeName(string$name,int$timestamp,int$flags= ?):bool

Establece la hora de modificación de una entrada definida por su nombre.

Parámetros

name

Nombre de la entrada.

timestamp

La hora de modificación (unix timestamp) del archivo.

flags

Flags opcionales, sin usar por ahora.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Este ejemplo crea un archivo ZIPtest.zipy añade al archivotest.txtcon su fecha de modificación.

Ejemplo #1 Archivar un fichero

<?php
$zip
= newZipArchive();
if (
$zip->open('test.zip',ZipArchive::CREATE) ===TRUE) {
$zip->addFile('text.txt');
$zip->setMtimeName('text.txt',mktime(0,0,0,12,25,2019));
$zip->close();
echo
"Ok\n";
} else {
echo
"KO\n";
}
?>

Notas

Nota:

Esta función sólo está disponible si se construye con libzip ≥ 1.0.0.

Ver también



ZipArchive::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPasswordEstablece la contraseña para el archivo activo

Descripción

publicZipArchive::setPassword(string$password):bool

Establece la contraseña para el archivo activo.

Parámetros

password

La contraseña a emplear para el archivo.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Notas

Nota:

A partir de PHP 7.2.0 y libzip 1.2.0 la contraseña se utiliza para descomprimir el archivo, y también es la contraseña por omisión paraZipArchive::setEncryptionName()yZipArchive::setEncryptionIndex(). Anteriormente, esta función sólo establecía la contraseña que se usaría para descomprimir el archivo; No se convirtió en un no protegido con contraseñaZipArchiveen un protegido con contraseñaZipArchive.

Ver también



ZipArchive::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndexObtiene los detalles de una entrada definida por su índice

Descripción

ZipArchive::statIndex(int$index,int$flags= ?):array

La función obtiene información acerca de la entrada definida por su índice.

Parámetros

index

Índice de la entrada

flags

ZipArchive::FL_UNCHANGEDpodría ser puesto con otros OR lógicos en él para pedir información acerca del fichero original en el archivo, ignorando cualquiera de los cambios hechos.

Valores devueltos

Devuelve una matríz conteniendo los detalles de la entrada, ofalseen caso de error.

Ejemplos

Ejemplo #1 Volcar la información estadística de una entrada

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip');
if (
$res===TRUE) {
print_r($zip->statIndex(3));
$zip->close();
} else {
echo
'falló, código:'.$res;
}
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [name] => foobar/baz
    [index] => 3
    [crc] => 499465816
    [size] => 27
    [mtime] => 1123164748
    [comp_size] => 24
    [comp_method] => 8
)


ZipArchive::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statNameObtener los detalles de una entrada definida por su nombre

Descripción

ZipArchive::statName(string$name,int$flags= ?):array

La función obtiene información acerca de la entrada definida por su nombre.

Parámetros

name

Nombre de la entrada

flags

El argumento flags especifica cómo la búsqueda del nombre debería se hecho. También,ZipArchive::FL_UNCHANGEDpodría ser puesta con otros OR en él para solicitar la información acerca del fichero original en el archivo, ignorando cualquier cambio realizado.

  • ZipArchive::FL_NOCASE

  • ZipArchive::FL_NODIR

  • ZipArchive::FL_UNCHANGED

Valores devueltos

Devuelve una matríz que contenie detalles de la entrada ofalseen caso de error.

Ejemplos

Ejemplo #1 Volcar la información estadística de una entrada

<?php
$zip
= newZipArchive;
$res=$zip->open('test.zip');
if (
$res===TRUE) {
print_r($zip->statName('foobar/baz'));
$zip->close();
} else {
echo
'falló, código:'.$res;
}
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [name] => foobar/baz
    [index] => 3
    [crc] => 499465816
    [size] => 27
    [mtime] => 1123164748
    [comp_size] => 24
    [comp_method] => 8
)


ZipArchive::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAllDeshacer todos los cambios hechos en el archivo

Descripción

ZipArchive::unchangeAll():bool

Deshacer todos los cambios hechos en el archivo.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchiveRevertir todos los cambios globales hechos en el archivo

Descripción

ZipArchive::unchangeArchive():bool

Revertir todos los cambios globales en el archivo. Por ahora, esto solamente revierte los cambios de los comentarios del archivo.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndexRevertir todos los cambios hechos a una entrada en el índice dado

Descripción

ZipArchive::unchangeIndex(int$index):bool

Revertir todos los cambios hechos a una entrada en el índice dado.

Parámetros

index

Índice de la entrada.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.



ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeNameDeshace todos los cambios realizados a una entrada con un nombre dado

Descripción

ZipArchive::unchangeName(string$name):bool

Deshacer todos los cambios hechos a una entrada.

Parámetros

name

Nombre de la entrada.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.


Tabla de contenidos



Funciones Zip


zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_closeCierra un fichero ZIP

Descripción

zip_close(resource$zip):void

Cierra el archivo ZIP archivo dado.

Parámetros

zip

Un fichero ZIP previamente abierto conzip_open().

Valores devueltos

No devuelve ningún valor.

Ver también



zip_entry_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_closeCierra la entrada a un directorio

Descripción

zip_entry_close(resource$zip_entry):bool

Cierra la entrada del directorio especificado.

Parámetros

zip_entry

Una entrada del directorio previamente abierto conzip_entry_open().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también



zip_entry_compressedsize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressedsizeObtiene el tamaño comprimido de una entrada de directorio

Descripción

zip_entry_compressedsize(resource$zip_entry):int

Devuelve el tamaño comprimido de una especifica entrada de directorio.

Parámetros

zip_entry

Una entrada de directorio devuelva porzip_read().

Valores devueltos

El tamaño comprimido.

Ver también



zip_entry_compressionmethod

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressionmethodDevuelve el método de compresión de una entrada de directorio

Descripción

zip_entry_compressionmethod(resource$zip_entry):string

Devuelve el método de compresión de una entrada de directorio especificada porzip_entry.

Parámetros

zip_entry

Una entrada de directorio devuelta porzip_read().

Valores devueltos

El método de compresión.

Ver también



zip_entry_filesize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_filesizeDevuelve el tamaño del fichero actual de una entrada de directorio

Descripción

zip_entry_filesize(resource$zip_entry):int

Devuelve el tamaño actual de una entrada de directorio específica.

Parámetros

zip_entry

Una entrada de directorio devuelva porzip_read().

Valores devueltos

El tamaño de una entrada de directorio.

Ver también



zip_entry_name

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_nameDevuelve el nombre de la entrada de un directorio

Descripción

zip_entry_name(resource$zip_entry):string

Devuelve el nombre de una entrada de directorio específica.

Parámetros

zip_entry

Una entrada de directorio devuelta porzip_read().

Valores devueltos

El nombre de la entrada de directorio.

Ver también



zip_entry_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_openAbrir una entrada de directorio para lectura

Descripción

zip_entry_open(resource$zip,resource$zip_entry,string$mode= ?):bool

Abre una entrada de directorio en un fichero zip para lectura.

Parámetros

zip

Un válido controlador de recurso es devuelto porzip_open().

zip_entry

Una entrada de directorio es devuelta porzip_read().

mode

Cualquiera de los modos especificados en la documentación defopen().

Nota:

Actualmente, elmodees ignorado y es siempre"rb". Esto es debido al hecho que el soporte zip en PHP es solamente de acceso lectura.

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Nota:

A diferencia defopen()y otras funciones similares, el valor devuelto porzip_entry_open()solo indica el resultado de la operación y no es necesario para la lectura o cerrado de la entrada de directorio.

Ver también



zip_entry_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_readLeer desde una entrada de directorio abierta

Descripción

zip_entry_read(resource$zip_entry,int$length= 1024):string

Lee desde una entrada de directorio abierta.

Parámetros

zip_entry

Un directorio devuelto porzip_read().

length

El número de bytes a devolver.

Nota:

Esto debería ser el tramo descomprimido que se desea leer.

Valores devueltos

Devuelve los datos leídos, un string vacío si se encuentra al final de un fichero, ofalseen case de error.

Ver también



zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_openAbre un fichero ZIP

Descripción

zip_open(string$filename):resource

Abre un nuevo fichero ZIP para su lectura.

Parámetros

filename

El nombre del fichero ZIP a abrir.

Valores devueltos

Devuelve un manejador del recurso para usarlo después conzip_read()yzip_close()o devolver el número de error sifilenameno existe o en caso de otro error.

Ver también



zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_readLeer la siguiente entrada en el fichero ZIP

Descripción

zip_read(resource$zip):resource

Lee la siguiente entrada en un fichero zip.

Parámetros

zip

Un fichero ZIP previamente abierto conzip_open().

Valores devueltos

Devuelve un recurso de una entrada de directorio para poder usar luego las funcioneszip_entry_..., ofalsesi no hay más entradas a leer, o código de error en caso de ocurrir otro error.

Ver también


Tabla de contenidos




Compresión Zlib


Introducción

Este módulo permite leer y escribir ficheros comprimidos con gzip (.gz) de forma transparente, a través de las versiones de la mayoría de las funciones desistemas de ficherosque trabajan con ficheros comprimidos con gzip (y también con ficheros descomprimidos, pero no con sockets).

Nota:

La versión 4.0.4 introdujo una envoltura basada en fopen para ficheros.gz, así que se puede usar la URL especialzlib:para acceder de forma trasparente a los ficheros comprimidos usando las funciones normales f*() de acceso a ficheros si se prefija el nombre de fichero o la ruta conzlib:cuando se llama afopen(). Esta característica requiere una biblioteca en tiempo de ejecución en C que provea la funciónfopencookie(). Hasta ahora, GNU libc parece ser la única biblioteca que ofrece esta característica.

En PHP 4.3.0,zlib:ha sido cambiado acompress.zlib://para evitar ambigüedades con los nombres de fichero que contengan caracteres ':'. La funciónfopencookie()ya no es necesaria. Hay más información disponible en la sección sobrezlib://.



Instalación/Configuración

Tabla de contenidos


Requerimientos

Este módulo usa las funciones de» zlibpor Jean-loup Gailly y Mark Adler. Se tiene que utilizar la versión >= 1.0.9 de zlib con éste módulo. Desde PHP 5.4.0 se tiene que usar zlib >= 1.2.0.4.



Instalación

El soporte para Zlib en PHP no está activado por defecto. Es necesario configurar PHP con la opción--with-zlib[=DIR]

La versión de PHP para Windows tiene soporte nativo para esta extensión. No se requiere cargar extensiones adicionales para utilizar estas funciones.



Configuración en tiempo de ejecución

El comportamiento de estas funciones se ve afectado por la configuración dephp.ini.

La extensión zlib ofrece la opción de comprimir de manera trasparente las páginas sobre la marcha, si el navegador que hace la solicitud lo soporta. Por lo tanto hay tres opciones en elarchivo de configuraciónphp.ini.

Opciones de Configuración de Zlib
NombrePor defectoCambiableHistorial de cambios
zlib.output_compression"0"PHP_INI_ALL 
zlib.output_compression_level"-1"PHP_INI_ALL 
zlib.output_handler""PHP_INI_ALL 
Para más detalles y definiciones de los modos de PHP_INI_*, veaDónde se puede realizar un ajuste de configuración.

He aquí una breve explicación de las directivas de configuración.

zlib.output_compressionbool/int

Para comprimir páginas transparentemente. Si esta opción está configurada en "On" enphp.inio en la configuración de Apache, las páginas serán comprimidas si el navegador envía un encabezado "Accept-Encoding: gzip" o "deflate". Los encabezados "Content-Encoding: gzip" (respectivamente "deflate") y "Vary: Accept-Encoding" serán agregados a la salida. En tiempo de ejecución, esto se puede configurar sólo antes de enviar cualquier salida.

Esta opción también acepta valores enteros (integer) en lugar de boolean en "On"/"Off", usando esto se puede configurar el tamaño del buffer de salida (por defecto es 4KB).

Nota:

output_handlerdebe estar vacío si ésta se configura en 'On' ! De otra manera se debe usarzlib.output_handler.

zlib.output_compression_levelint

Nivel de compresión usado para la salida de la compresión transparente. Especifica un valor entre 0 (no comprimido) y 9 (máxima compresión). El valor por defecto es -1, que deja que el servidor decida cual nivel utilizar.

zlib.output_handlerstring

No se pueden especificar manejadores adicionales de salida si zlib.output_compression está activada aquí. Esta configuración hace lo mismo queoutput_handlerpero en un orden diferente.



Tipos de recursos

Esta extensión define un recurso de archivo puntero retornado porgzopen().




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

FORCE_GZIP(integer)
FORCE_DEFLATE(integer)
ZLIB_ENCODING_RAW(integer)
Algoritmo DEFLATE según RFC 1951. Disponible desde PHP 7.0.0.
ZLIB_ENCODING_DEFLATE(integer)
Algoritmo de compresión ZLIB según RFC 1950. Disponible desde PHP 7.0.0.
ZLIB_ENCODING_GZIP(integer)
Algoritmo GZIP según RFC 1952. Disponible desde PHP 7.0.0.
ZLIB_FILTERED(integer)
Disponible desde PHP 7.0.0.
ZLIB_HUFFMAN_ONLY(integer)
Disponible desde PHP 7.0.0.
ZLIB_FIXED(integer)
Disponible desde PHP 7.0.0.
ZLIB_RLE(integer)
Disponible desde PHP 7.0.0.
ZLIB_DEFAULT_STRATEGY(integer)
Disponible desde PHP 7.0.0.
ZLIB_BLOCK(integer)
Disponible desde PHP 7.0.0.
ZLIB_NO_FLUSH(integer)
Disponible desde PHP 7.0.0.
ZLIB_PARTIAL_FLUSH(integer)
Disponible desde PHP 7.0.0.
ZLIB_SYNC_FLUSH(integer)
Disponible desde PHP 7.0.0.
ZLIB_FULL_FLUSH(integer)
Disponible desde PHP 7.0.0.
ZLIB_FINISH(integer)
Disponible desde PHP 7.0.0.


Ejemplos

Este ejemplo abre un archivo temporal y escribe una cadena de prueba en él, entonces muestra el contenido de este archivo dos veces.

Ejemplo #1 Pequeño Ejemplo de Zlib

<?php

$filename
=tempnam('/tmp','zlibtest') .'.gz';
echo
"<html>\n<head></head>\n<body>\n<pre>\n";
$s="Sólo una prueba, prueba, prueba, prueba, prueba, prueba!\n";

// abre el archivo para escribir con compresión máxima
$zp=gzopen($filename,"w9");

// escribe la cadena en el archivo
gzwrite($zp,$s);

// cierra el archivo
gzclose($zp);

// abre el archivo para lectura
$zp=gzopen($filename,"r");

// lee el tercer carácter
echogzread($zp,3);

// salida hasta el fin del archivo y lo cierra
gzpassthru($zp);
gzclose($zp);

echo
"\n";

// abre el archivo y muestra el contenido (por segunda vez).
if (readgzfile($filename) !=strlen($s)) {
echo
"Error con funciones de zlib!";
}
unlink($filename);
echo
"</pre>\n</body>\n</html>\n";

?>

Ejemplo #2 Trabajando con la API de compresión y descompresión increemental desde PHP 7.0.0

// Perform GZIP compression:
$deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
$compressed = deflate_add($deflateContext, "Data to compress", ZLIB_NO_FLUSH);
$compressed .= deflate_add($deflateContext, ", more data", ZLIB_NO_FLUSH);
$compressed .= deflate_add($deflateContext, ", and even more data!", ZLIB_FINISH);?>

// Perform GZIP decompression:
$inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
$uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
$uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
echo $uncompressed;

El resultado del ejemplo sería:

Data to compress, more data, and even more data!


Funciones de Zlib


deflate_add

(PHP 7, PHP 8)

deflate_addIncrementally deflate data

Descripción

deflate_add(DeflateContext$context,string$data,int$flush_mode=ZLIB_SYNC_FLUSH):string|false

Incrementally deflates data in the specified context.

Parámetros

context

A context created withdeflate_init().

data

A chunk of data to compress.

flush_mode

One ofZLIB_BLOCK,ZLIB_NO_FLUSH,ZLIB_PARTIAL_FLUSH,ZLIB_SYNC_FLUSH(default),ZLIB_FULL_FLUSH,ZLIB_FINISH. Normally you will want to setZLIB_NO_FLUSHto maximize compression, andZLIB_FINISHto terminate with the last chunk of data. See the» zlib manualfor a detailed description of these constants.

Valores devueltos

Returns a chunk of compressed data, ofalseen caso de error.

Errores/Excepciones

If invalid arguments are given, an error of levelE_WARNINGis generated.

Historial de cambios

VersiónDescripción
8.0.0contextexpects aDeflateContextinstance now; previously, aresourcewas expected.

Ver también



deflate_init

(PHP 7, PHP 8)

deflate_initInitialize an incremental deflate context

Descripción

deflate_init(int$encoding,array$options= []):DeflateContext|false

Initializes an incremental deflate context using the specifiedencoding.

Note that thewindowoption here only sets the window size of the algorithm, differently from the zlib filters where the same parameter also sets the encoding to use; the encoding must be set with theencodingparameter.

Limitation: there is currently no way to set the header information on a GZIP compressed stream, which are set as follows: GZIP signature (\x1f\x8B); compression method (\x08== DEFLATE); 6 zero bytes; the operating system set to the current system (\x00= Windows,\x03= Unix, etc.)

Parámetros

encoding

One of theZLIB_ENCODING_*constants.

options

An associative array which may contain the following elements:

level

The compression level in range -1..9; defaults to -1.

memory

The compression memory level in range 1..9; defaults to 8.

window

The zlib window size (logarithmic) in range8..15; defaults to15. zlib changes a window size of8to9, and as of zlib 1.2.8 fails with a warning, if a window size of8is requested forZLIB_ENCODING_RAWorZLIB_ENCODING_GZIP.

strategy

One ofZLIB_FILTERED,ZLIB_HUFFMAN_ONLY,ZLIB_RLE,ZLIB_FIXEDorZLIB_DEFAULT_STRATEGY(the default).

dictionary

Astringor anarrayofstringsof the preset dictionary (default: no preset dictionary).

Valores devueltos

Returns a deflate context resource (zlib.deflate) on success, ofalseen caso de error.

Errores/Excepciones

If an invalid option is passed tooptionsor the context couldn't be created, an error of levelE_WARNINGis generated.

Historial de cambios

VersiónDescripción
8.0.0On success, this function returns aDeflateContextinstance now; previously, aresourcewas returned.

Ver también



gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzcloseCierra el apuntador de un archivo gz abierto

Descripción

gzclose(resource$stream):bool

Cierra el apuntador del archivo gz dado.

Parámetros

stream

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo degzclose()

<?php
$gz
=gzopen('somefile.gz','w9');
gzputs($gz,'I was added to somefile.gz');
gzclose($gz);
?>

Ver también



gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompressComprime una cadena

Descripción

gzcompress(string$data,int$level= -1,int$encoding=ZLIB_ENCODING_DEFLATE):string|false

Esta función comprime la cadena dada usando el formato de datosZLIB.

Para detalles sobre el algoritmo de compresión ZLIB, ver el documento "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950).

Nota:

Estonoes lo mismo que la compresión que gzip, la cuál incluye algunos encabezados de datos. Vergzencode()para la compresión gzip.

Parámetros

data

Los datos a comprimir.

level

El nivel de compresión. Se puede dar como 0 para ninguna compresión, hasta 9 para la máxima compresión.

Si se utiliza -1, se usará la compresión por defecto de la librería zlib la cual es 6.

encoding

Una de las constentesZLIB_ENCODING_*.

Valores devueltos

La cadena comprimida ofalsesi ocurre un error.

Ejemplos

Ejemplo #1 Ejemplo degzcompress()

<?php
$compressed
=gzcompress('Compress me',9);
echo
$compressed;
?>

Ver también



gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecodeDecodifica una cadena comprimida con gzip

Descripción

gzdecode(string$data,int$max_length= 0):string|false

Está función retorna una versión decodificada de la entradadata.

Parámetros

data

Los datos para decodificar, codificados congzencode().

max_length

La longitud máxima de datos que decodificar.

Valores devueltos

La cadena decodificada ofalsesi ocurre un error.

Ver también



gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflateComprime una cadena

Descripción

gzdeflate(string$data,int$level= -1,int$encoding=ZLIB_ENCODING_RAW):string|false

Esta función comprime la cadena dada utilizando el formato de datosDEFLATE.

Para más detalles sobre el algoritmo de compresión DEFLATE ver el documento "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951).

Parámetros

data

Los datos a comprimir.

level

El nivel de compresión. Se puede dar desde 0 para ninguna compresión hasta 9 para máxima compresión. Si no se especifica, se utilizará el nivel de compresión por defecto de la librería zlib.

encoding

Una de las constantesZLIB_ENCODING_*.

Valores devueltos

La cadena comprimida ofalsesi ocurre un error.

Ejemplos

Ejemplo #1 Ejemplo degzdeflate()

<?php
$compressed
=gzdeflate('Compress me',9);
echo
$compressed;
?>

Ver también



gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencodeCrea una cadena comprimida con gzip

Descripción

gzencode(string$data,int$level= -1,int$encoding_mode= FORCE_GZIP):string

Esta función retorna una versión comprimida de ladatade entrada, compatible con la salida del programagzip.

Para más información sobre el formato de archivo GZIP, ver el documento:» GZIP file format specification version 4.3(RFC 1952).

Parámetros

data

Los datos a codificar.

level

El nivel de compresión. Se puede dar como 0 para ninguna compresión, hasta 9 para la máxima compresión. Si no se incluye, se utilizará el nivel de compresión por defecto de la librería zlib.

encoding_mode

El modo de codificación. Puede serFORCE_GZIP(por defecto) oFORCE_DEFLATE.

Antes de PHP 5.4.0, utilizarFORCE_DEFLATEresultaba en un string comprimido zlib estándar (incluyendo encabezados de la librería) después del encabezado de archivo gzip pero sin el cierre de la suma de control crc32.

En PHP 5.4.0 y posterior,FORCE_DEFLATEgenera una salida que cumple el RFC 1950, consistente en un encabezado zlib, los datos comprimidos y una suma de control Adler.

Valores devueltos

La cadena codificada ofalsesi ocurre un error.

Historial de cambios

VersiónDescripción
5.4.0FORCE_DEFLATEahora genera una salida que cumple el RFC 1950.

Ejemplos

Los datos resultantes contienen los encabezados y estructura de datos apropiados para construir un archivo .gz estándar, por ejemplo:

Ejemplo #1 Creando un archivo gzip

<?php
$data
=implode("",file("bigfile.txt"));
$gzdata=gzencode($data,9);
$fp=fopen("bigfile.txt.gz","w");
fwrite($fp,$gzdata);
fclose($fp);
?>

Ver también



gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeofPrueba de apuntador paraEOFde archivo gz

Descripción

gzeof(resource$stream):bool

Prueba el apuntador de archivo GZ dado en busca delEOF(fin de archivo).

Parámetros

stream

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

Valores devueltos

Retornatruesi el apuntador GZ está alEOFdel archivo o si ocurrió un error; de lo contrario retornafalse.

Ejemplos

Ejemplo #1 Ejemplo degzeof()

<?php
$gz
=gzopen('somefile.gz','r');
while (!
gzeof($gz)) {
echo
gzgetc($gz);
}
gzclose($gz);
?>



gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfileLee un archivo gz completo en una matriz

Descripción

gzfile(string$filename,int$use_include_path= 0):array|false

Está función es identica areadgzfile(), excepto que retorna el archivo en una matriz.

Parámetros

filename

El nombre del archivo.

use_include_path

Se puede asignar este parámetro opcional en1, si se desea buscar también el archivo en la rutainclude_path.

Valores devueltos

Una matriz que contiene el archivo, una línea por celda, incluidas líneas vacías, y con líneas nuevas aún unidas, ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo degzfile()

<?php
$lines
=gzfile('somefile.gz');
foreach (
$linesas$line) {
echo
$line;
}
?>

Ver también



gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetcObtiene el caracter donde está el apuntador al archivo gz

Descripción

gzgetc(resource$stream):string|false

Retorna una cadena que contiene un solo caracter (sin comprimir) leído del apuntador al archivo gz dado.

Parámetros

stream

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

Valores devueltos

El caracter sin comprimir ofalseen caso deEOF(a diferencia degzeof()).

Ejemplos

Ejemplo #1 Ejemplo degzgetc()

<?php
$gz
=gzopen('somefile.gz','r');
while (!
gzeof($gz)) {
echo
gzgetc($gz);
}
gzclose($gz);
?>

Ver también

  • gzopen()- Abre un archivo gz
  • gzgets()- Obtiene la línea del apuntador al archivo



gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetsObtiene la línea del apuntador al archivo

Descripción

gzgets(resource$zp,int$length= ?):string

Obtiene una cadena (sin comprimir) de hasta un largo de - 1 bytes leídos desde el apuntador al archivo dado. La lectura termina cuando el largo de - 1 bytes ha sido leído, en un salto de línea o cuando se alcance el fin del archivo (EOF), lo que ocurra primero.

Parámetros

zp

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

length

La longitud de los datos a obtener.

Valores devueltos

La cadena sin comprimir ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo degzgets()

<?php
$handle
=gzopen('somefile.gz','r');
while (!
gzeof($handle)) {
$buffer=gzgets($handle,4096);
echo
$buffer;
}
gzlose($handle);;
?>

Ver también

  • gzopen()- Abre un archivo gz
  • gzgetc()- Obtiene el caracter donde está el apuntador al archivo gz
  • gzwrite()- Escritura en un archivo gz, segura a nivel binario



gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetssObtiene la línea del apuntador al archivo gz y retira las etiquetas HTML

Advertencia

Esta función ha sido declaradaOBSOLETAa partir de PHP 7.3.0. Su uso está totalmente desaconsejado.

Descripción

gzgetss(resource$zp,int$length,string$allowable_tags= ?):string

Función identica agzgets(), excepto quegzgetss()intenta retirar cualquier etiqueta HTML y PHP del texto que esta leyendo.

Parámetros

zp

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

length

La longitud de los datos a obtener.

allowable_tags

Se puede usar éste parámetro opcional para especificar cuales etiquetas no se deben retirar.

Valores devueltos

La cadena descomprimida y sin etiquetas ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo degzgetss()

<?php
$handle
=gzopen('somefile.gz','r');
while (!
gzeof($handle)) {
$buffer=gzgetss($handle,4096);
echo
$buffer;
}
gzlose($handle);
?>

Ver también



gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflateDescomprime una cadena comprimida

Descripción

gzinflate(string$data,int$max_length= 0):string|false

Esta función descomprime una cadena comprimida.

Parámetros

data

Los datos comprimidos congzdeflate().

max_length

La longitud máxima de datos a decodificar.

Valores devueltos

Los datos originales descomprimidos ofalseen caso de error.

La función retornará un error si los datos descomprimidos son más de 32768 veces la longitud de ladatade entrada o mayores que el parámetro opcionalmax_length.

Ejemplos

Ejemplo #1 Ejemplo degzinflate()

<?php
$compressed
=gzdeflate('Compress me',9);
$uncompressed=gzinflate($compressed);
echo
$uncompressed;
?>

Ver también



gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopenAbre un archivo gz

Descripción

gzopen(string$filename,string$mode,int$use_include_path= 0):resource|false

Abre un archivo gzip (.gz) para lectura o escritura.

gzopen()se puede usar para leer un archivo el cual no esté en formato gzip; en este casogzread()leerá directamente el archivo sin descomprimirlo.

Parámetros

filename

El nombre del archivo.

mode

Como enfopen()(rbowb) pero también puede incluir un nivel de compresión (wb9) u una estrategia:fpara datos filtrados como enwb6f,hparacompresión Huffman solamentecomo enwb1h. (Ver la descripción dedeflateInit2enzlib.hpara más información sobre el parámetro de estrategia.)

use_include_path

Se puede configurar este parámetro opcional en1, si se desea buscar también el archivo en la rutainclude_path.

Valores devueltos

Retorna un apuntador hacia el archivo abierto, después de eso, cualquier cosa que se lea desde este descriptor de archivo sera descomprimido de forma transparente y lo que se escriba será comprimido.

Si falla la apertura, la función retornafalse.

Ejemplos

Ejemplo #1 Ejemplo degzopen()

<?php
$fp
=gzopen("/tmp/file.gz","r");
?>

Ver también

  • gzclose()- Cierra el apuntador de un archivo gz abierto



gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthruMuestra todos los datos restantes a partir del apuntador al achivo gz

Descripción

gzpassthru(resource$zp):int

Lee hasta elEOFdesde la posición en el apuntador al archivo gz y escribe los resultados (sin comprimir) en la salida estándar.

Nota:

Se puede necesitar llamar a la funcióngzrewind()para restablecer el apuntador al inicio del archivo, si ya se han escrito datos en él.

Sugerencia

Si sólo se desea volcar el contenido de un archivo en el buffer de salida, sin modificarlo primero o buscando una posición particular, se puede usar la funciónreadgzfile(), la cual ahorra el llamado a la funcióngzopen().

Parámetros

zp

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

Valores devueltos

El número de carácteres sin comprimir leídos degzy pasados a través de la entrada, ofalseen caso de error.

Ejemplos

Ejemplo #1 Ejemplo degzpassthru()

<?php
$fp
=gzopen('file.gz','r');
gzpassthru($fp);
gzclose($fp);
?>



gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputsAlias degzwrite()

Descripción

Esta función es un alias de:gzwrite().



gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzreadLectura de archivo gz segura a nivel binario

Descripción

gzread(resource$zp,int$length):string

gzread()lee los bytes hasta el parámetrolengthdesde el apuntador al archivo gz dado. La lectura se detiene cuando los bytes del parámetrolength(sin comprimir) sean leídos o cuando se alcance el fin del archivo (EOF), lo que ocurra primero.

Parámetros

zp

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

length

El número de bytes a leer.

Valores devueltos

Los datos que han sido leídos.

Ejemplos

Ejemplo #1 Ejemplo degzread()

<?php
// pasar los contenidos de un archivo gz a una cadena
$filename="/usr/local/something.txt.gz";
$zd=gzopen($filename,"r");
$contents=gzread($zd,10000);
gzclose($zd);
?>

Ver también

  • gzwrite()- Escritura en un archivo gz, segura a nivel binario
  • gzopen()- Abre un archivo gz
  • gzgets()- Obtiene la línea del apuntador al archivo
  • gzgetss()- Obtiene la línea del apuntador al archivo gz y retira las etiquetas HTML
  • gzfile()- Lee un archivo gz completo en una matriz
  • gzpassthru()- Muestra todos los datos restantes a partir del apuntador al achivo gz



gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewindReinicia la posición del apuntador a un archivo gz

Descripción

gzrewind(resource$stream):bool

Coloca el indicador de posición del apuntador al archivo gz dado al comienzo del flujo del archivo.

Parámetros

stream

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también

  • gzseek()- Ubica el apuntador a un archivo gz
  • gztell()- Indica la posición de lectura/escritura del apuntador al archivo gz



gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseekUbica el apuntador a un archivo gz

Descripción

gzseek(resource$zp,int$offset,int$whence= SEEK_SET):int

Establece el indicador de posición para el apuntador al archivo dado en el desplazamiento de bytes fijado en el flujo del archivo. Es equivalente a llamar (en C) agzseek(zp, offset, SEEK_SET).

Si el archivo está abierto para lectura, ésta función es emulada pero puede ser extremadamente lenta. Si el archivo está abierto para escritura, sólo está soportada la búsqueda hacia adelante; entoncesgzseek()comprime una secuencia de ceros hasta la nueva posición de inicio.

Parámetros

zp

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

offset

El desplazamiento buscado.

whence

Los valores dewhenceson:

  • SEEK_SET- Establece la posición igual aloffsetde bytes.
  • SEEK_CUR- Establece la posición en la posición actual más eloffset.

Siwhenceno se especifica, se asume que esSEEK_SET.

Valores devueltos

En caso de éxito, retorna 0; en caso contrario, devuelve -1. Notese que buscar pasado el EOF no es considerado un error.

Ejemplos

Ejemplo #1 Ejamplo degzseek()

<?php
$gz
=gzopen('somefile.gz','r');
gzseek($gz,2);
echo
gzgetc($gz);
gzclose($gz);
?>

Ver también

  • gztell()- Indica la posición de lectura/escritura del apuntador al archivo gz
  • gzrewind()- Reinicia la posición del apuntador a un archivo gz



gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztellIndica la posición de lectura/escritura del apuntador al archivo gz

Descripción

gztell(resource$zp):int

Obtiene la posición del apuntador al archivo dado; por ejemplo, su desplazamiento en el flujo del archivo sin comprimir.

Parámetros

zp

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

Valores devueltos

La posición del apuntador al archivo ofalsesi ocurre un error.

Ver también

  • gzopen()- Abre un archivo gz
  • gzseek()- Ubica el apuntador a un archivo gz
  • gzrewind()- Reinicia la posición del apuntador a un archivo gz



gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompressDescomprime una cadena comprimida

Descripción

gzuncompress(string$data,int$length= 0):string

Está función descomprime una cadena comprimida

Parámetros

data

Los datos comprimidos congzcompress().

length

La longitud máxima de datos a decodificar.

Valores devueltos

Los datos originales sin comprimir ofalseen caso de error.

La función retornará un error si los datos descomprimidos son más de 32768 veces la longitud de la entrada comprimidadatao mayores que el parámetro opcionallength.

Ejemplos

Ejemplo #1 Ejemplo degzuncompress()

<?php
$compressed
=gzcompress('Compress me',9);
$uncompressed=gzuncompress($compressed);
echo
$uncompressed;
?>

Ver también



gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwriteEscritura en un archivo gz, segura a nivel binario

Descripción

gzwrite(resource$zp,string$string,int$length= ?):int

gzwrite()escribe el contenido decadenaal archivo gz dado.

Parámetros

zp

El apuntador al archivo gz. Debe ser válido y debe apuntar a un archivo abierto exitosamente porgzopen().

string

La cadena a escribir.

length

El número de bytes sin comprimir a escribir. Si se suministra, la escritura se detendrá después de que se hayan escrito los bytes (sin comprimir) del parámetrolengtho de que sea alcanzado el fin de lastring, lo que ocurra primero.

Nota:

Nótese que si se da el argumentolength, entonces la opción de configuraciónmagic_quotes_runtimeserá ignorada y ningún slash será retirado de lastring.

Valores devueltos

Retorna el número de bytes (sin comprimir) escritos en el flujo del archivo gz dado.

Ejemplos

Ejemplo #1 Ejemplo degzwrite()

<?php
$string
='Some information to compress';
$gz=gzopen('somefile.gz','w9');
gzwrite($gz,$string);
gzclose($gz);
?>

Ver también

  • gzread()- Lectura de archivo gz segura a nivel binario
  • gzopen()- Abre un archivo gz



inflate_add

(PHP 7, PHP 8)

inflate_addIncrementally inflate encoded data

Descripción

inflate_add(InflateContext$context,string$data,int$flush_mode=ZLIB_SYNC_FLUSH):string|false

Incrementally inflates encoded data in the specifiedcontext.

Limitation: header information from GZIP compressed data are not made available.

Parámetros

context

A context created withinflate_init().

data

A chunk of compressed data.

flush_mode

One ofZLIB_BLOCK,ZLIB_NO_FLUSH,ZLIB_PARTIAL_FLUSH,ZLIB_SYNC_FLUSH(default),ZLIB_FULL_FLUSH,ZLIB_FINISH. Normally you will want to setZLIB_NO_FLUSHto maximize compression, andZLIB_FINISHto terminate with the last chunk of data. See the» zlib manualfor a detailed description of these constants.

Valores devueltos

Returns a chunk of uncompressed data, ofalseen caso de error.

Errores/Excepciones

If invalid parameters are given, inflating the data requires a preset dictionary, but none is specified, the compressed stream is corrupt or has an invalid checksum, an error of levelE_WARNINGis generated.

Historial de cambios

VersiónDescripción
8.0.0contextexpects anInflateContextinstance now; previously, aresourcewas expected.

Ver también



inflate_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_lenGet number of bytes read so far

Descripción

inflate_get_read_len(InflateContext$context):int

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

context

Valores devueltos

Returns number of bytes read so far ofalseen caso de error.

Historial de cambios

VersiónDescripción
8.0.0contextexpects anInflateContextinstance now; previously, aresourcewas expected.


inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_statusGet decompression status

Descripción

inflate_get_status(InflateContext$context):int

Usually returns eitherZLIB_OKorZLIB_STREAM_END.

Parámetros

context

Valores devueltos

Returns decompression status ofalseen caso de error.

Historial de cambios

VersiónDescripción
8.0.0contextexpects anInflateContextinstance now; previously, aresourcewas expected.


inflate_init

(PHP 7, PHP 8)

inflate_initInitialize an incremental inflate context

Descripción

inflate_init(int$encoding,array$options= []):InflateContext|false

Initialize an incremental inflate context with the specifiedencoding.

Parámetros

encoding

One of theZLIB_ENCODING_*constants.

options

An associative array which may contain the following elements:

level

The compression level in range -1..9; defaults to -1.

memory

The compression memory level in range 1..9; defaults to 8.

window

The zlib window size (logarithmic) in range 8..15; defaults to 15.

strategy

One ofZLIB_FILTERED,ZLIB_HUFFMAN_ONLY,ZLIB_RLE,ZLIB_FIXEDorZLIB_DEFAULT_STRATEGY(the default).

dictionary

Astringor anarrayofstringsof the preset dictionary (default: no preset dictionary).

Valores devueltos

Returns an inflate context resource (zlib.inflate) on success, ofalseen caso de error.

Errores/Excepciones

If an invalid encoding or option is passed tooptions, or the context couldn't be created, an error of levelE_WARNINGis generated.

Historial de cambios

VersiónDescripción
8.0.0On success, this function returns anInflateContextinstance now; previously, aresourcewas returned.

Ver también



readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfileMuestra un archivo gz

Descripción

readgzfile(string$filename,int$use_include_path= 0):int

Lee un archivo, lo descomprime y lo escribe en la salida estándar.

La funciónreadgzfile()puede ser usada para leer un archivo que no esté en formato gzip; en éste casoreadgzfile()leerá directamente el archivo sin hacer la descompresión.

Parámetros

filename

El nombre del archivo. Este archivo será abierto del sistema de archivos y sus contenidos escritos en la salida estándar.

use_include_path

Se puede especificar éste parámetro opcional en1, si también se desea buscar el archivo en la rutainclude_path.

Valores devueltos

Devuelve el número de bytes (sin comprimir) leídos del archivo en caso de éxito, ofalseen caso de error

Errores/Excepciones

En caso de fallo, se emite unE_WARNING.

Ver también

  • gzpassthru()- Muestra todos los datos restantes a partir del apuntador al achivo gz
  • gzfile()- Lee un archivo gz completo en una matriz
  • gzopen()- Abre un archivo gz



zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decodeDescomprime datos codificados en craw/gzip/zlib

Descripción

zlib_decode(string$data,string$max_decoded_len= ?):string

Descomprime datos codificados en raw/gzip/zlib.

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

data

max_decoded_len

Valores devueltos

Devuelve los datos no comprimidos, ofalseen caso de error.

Ver también



zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encodeComprime datos con la codificación especificada

Descripción

zlib_encode(string$data,int$encoding,int$level= -1):string

Comprime datos con la codificación especificada.

Advertencia

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

Parámetros

data

Los datos a comprimir.

encoding

El algoritmo de compresión. O bienZLIB_ENCODING_RAW,ZLIB_ENCODING_DEFLATEoZLIB_ENCODING_GZIP.

level

Valores devueltos

Ejemplos

Ejemplo #1 Ejemplo dezlib_encode()

<?php
$str
='hello world';
$enc=zlib_encode($str,ZLIB_ENCODING_DEFLATE);
echo
bin2hex($enc);
?>

El resultado del ejemplo sería:

789ccb48cdc9c95728cf2fca4901001a0b045d

Ver también



zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_typeRetorna el tipo de codificación utilizada para hacer la compresión

Descripción

zlib_get_coding_type():string

Retorna el tipo de codificación utilizada para hacer la compresión.

Valores devueltos

Los posibles valores de retorno songzip,deflateofalse.

Ver también


Tabla de contenidos

  • deflate_add— Incrementally deflate data
  • deflate_init— Initialize an incremental deflate context
  • gzclose— Cierra el apuntador de un archivo gz abierto
  • gzcompress— Comprime una cadena
  • gzdecode— Decodifica una cadena comprimida con gzip
  • gzdeflate— Comprime una cadena
  • gzencode— Crea una cadena comprimida con gzip
  • gzeof— Prueba de apuntador para EOF de archivo gz
  • gzfile— Lee un archivo gz completo en una matriz
  • gzgetc— Obtiene el caracter donde está el apuntador al archivo gz
  • gzgets— Obtiene la línea del apuntador al archivo
  • gzgetss— Obtiene la línea del apuntador al archivo gz y retira las etiquetas HTML
  • gzinflate— Descomprime una cadena comprimida
  • gzopen— Abre un archivo gz
  • gzpassthru— Muestra todos los datos restantes a partir del apuntador al achivo gz
  • gzputs— Alias de gzwrite
  • gzread— Lectura de archivo gz segura a nivel binario
  • gzrewind— Reinicia la posición del apuntador a un archivo gz
  • gzseek— Ubica el apuntador a un archivo gz
  • gztell— Indica la posición de lectura/escritura del apuntador al archivo gz
  • gzuncompress— Descomprime una cadena comprimida
  • gzwrite— Escritura en un archivo gz, segura a nivel binario
  • inflate_add— Incrementally inflate encoded data
  • inflate_get_read_len— Get number of bytes read so far
  • inflate_get_status— Get decompression status
  • inflate_init— Initialize an incremental inflate context
  • readgzfile— Muestra un archivo gz
  • zlib_decode— Descomprime datos codificados en craw/gzip/zlib
  • zlib_encode— Comprime datos con la codificación especificada
  • zlib_get_coding_type— Retorna el tipo de codificación utilizada para hacer la compresión


La clase DeflateContext

(PHP 8)

Introducción

Una clase completamente opaca que reemplaza los recursoszlib.deflatea partir de PHP 8.0.0.

Sinopsis de la Clase

finalclassDeflateContext{
}


The InflateContext class

(PHP 8)

Introducción

A fully opaque class which replaceszlib.inflateresources as of PHP 8.0.0.

Sinopsis de la Clase

finalclassInflateContext{
}




Extensiones criptográficas


HASH Framework para cifrar mensajes


Introducción

Motor para cifrar mensajes (hash). Permite la transformación directa o incremental de mensajes de longitud arbitraria usando una variedad de algoritmos hash.



Instalación/Configuración

Tabla de contenidos


Requerimientos

No se requiere de ninguna instalación para utilizar estas funciones; forman parte del núcleo de PHP.



Instalación

A partir de PHP 5.1.2, la extensión Hash está incluida y copilada en PHP de forma predeterminada.

Se puede deshabilitar explícitamente utilizando la opción --disable-hash de la configuración. En versiones anteriores de PHP se puede incorporar la extensión Hash instalando el» módulo PECL.



Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración definidas enphp.ini.



Tipos de recursos

Esta extensión define un recurso de Contexto de Hash devuelto porhash_init().




Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles sólo cuando la extensión haya sido compilada con PHP, o bien sea cargada dinámicamente en ejecución.

HASH_HMAC(integer)
Bandera opcional parahash_init(). Indica que el algoritmo de cifrado de claves HMAC debe ser aplicado al contexto actual de hashing.


Funciones de hash


hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algosDevuelve una lista con los algoritmos de cifrado soportados

Descripción

hash_algos():array

Valores devueltos

Devuelve un array numérico que contiene una lista con los tipos de algoritmos de cifrado soportados.

Historial de cambios

VersiónDescripción
5.6.0Se añadió soprte para gost-crypto. Este implementa la función de hash GOST empleando las tablas CryptoPro S-box como está especificado en la» RFC 4357, sección 11.2.
5.4.0Se añade soporte para joaat, fnv132 y para fnv164. Soporte para Salsa10 y Salsa20 fué eliminado.
5.3.0Se añade soporte para md2, ripemd256, ripemd320, salsa10, salsa20, snefru256 y para sha224

Ejemplos

Ejemplo #1hash_algos()ejemplo

A partir de PHP 5.6.0,hash_algos()devuelve la siguiente lista de nombres de algoritmos.

<?php
print_r
(hash_algos());
?>

El resultado del ejemplo sería algo similar a:

Array
(
    [0] => md2
    [1] => md4
    [2] => md5
    [3] => sha1
    [4] => sha224
    [5] => sha256
    [6] => sha384
    [7] => sha512
    [8] => ripemd128
    [9] => ripemd160
    [10] => ripemd256
    [11] => ripemd320
    [12] => whirlpool
    [13] => tiger128,3
    [14] => tiger160,3
    [15] => tiger192,3
    [16] => tiger128,4
    [17] => tiger160,4
    [18] => tiger192,4
    [19] => snefru
    [20] => snefru256
    [21] => gost
    [22] => gost-crypto
    [23] => adler32
    [24] => crc32
    [25] => crc32b
    [26] => fnv132
    [27] => fnv1a32
    [28] => fnv164
    [29] => fnv1a64
    [30] => joaat
    [31] => haval128,3
    [32] => haval160,3
    [33] => haval192,3
    [34] => haval224,3
    [35] => haval256,3
    [36] => haval128,4
    [37] => haval160,4
    [38] => haval192,4
    [39] => haval224,4
    [40] => haval256,4
    [41] => haval128,5
    [42] => haval160,5
    [43] => haval192,5
    [44] => haval224,5
    [45] => haval256,5
)



hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copyCopia un recurso de contexto de cifrado

Descripción

hash_copy(resource$context):resource

Parámetros

context

Contexto para cifrado que se obtiene mediantehash_init().

Valores devueltos

Devuelve una copia del recurso de un contexto de cifrado.

Ejemplos

Ejemplo #1Ejemplo de hash_copy()

<?php
$context
=hash_init("md5");
hash_update($context,"data");

/* copy context to be able to continue using it */
$copy_context=hash_copy($context);

echo
hash_final($context),"\n";

hash_update($copy_context,"data");
echo
hash_final($copy_context),"\n";
?>

El resultado del ejemplo sería:

8d777f385d3dfec8815d20f7496026dc
511ae0b1c13f95e5f08f1a0dd3da3d93



hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equalsComparación de strings segura contra ataques de temporización

Descripción

hash_equals(string$known_string,string$user_string):bool

Compara dos strings empleando el mismo tiempo, sin importar si son iguales o no.

Esta función debería utilizarse para mitigar los ataques de temporización, por ejemplo, al probar hash de contraseñas decrypt().

Parámetros

known_string

Elstringde longitud conocida con el que comparar

user_string

El string proporcionado por el usuario

Valores devueltos

Devuelvetruecuando los dos strings son iguales, ofalsesi no.

Errores/Excepciones

Emite un mensaje de nivelE_WARNINGcuando ninguno de los parámetros proporcionados es un string.

Ejemplos

Ejemplo #1 Ejemplohash_equals()

<?php
$esperado
=crypt('12345','$2a$07$usesomesillystringforsalt$');
$correcto=crypt('12345','$2a$07$usesomesillystringforsalt$');
$incorrecto=crypt('apple','$2a$07$usesomesillystringforsalt$');

var_dump(hash_equals($esperado,$correcto));
var_dump(hash_equals($esperado,$incorrecto));
?>

El resultado del ejemplo sería:

bool(true)
bool(false)

Notas

Nota:

Ambos argumentos deber tener la misma longitud para que se puedan comparar. Cuando se proporcionan argumentos con diferente longitud, se devuelvefalseinmediatamente, pudiéndose filtrar la longitud del string conocido en caso de un ataque de temporización.

Nota:

Es importante proveer el string proporcionado por el usuario como segundo parámetro, en vez de como el primero.



hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_fileGenerar un valor hash usando el contenido de un fichero dado

Descripción

hash_file(string$algo,string$filename,bool$raw_output=false):string

Parámetros

algo

Nombre del algoritmo hash seleccionado (es decir "md5", "sha256", "haval160,4", etc..). Para una lista de los algoritmos soportados véasehash_algos().

filename

URL que describe la ubicación del fichero que se va a procesar; Soporta envoltorios abiertos (fopen).

raw_output

Cuando se establece entruela salida serán datos binarios sin formato,falsela salida serán dígitos hexadecimales en minúsculas.

Valores devueltos

Devuelve un string que contiene el resumen del mensaje calculado como hexágonos en minúsculas a menos que el parámetroraw_outputsea establecido en cuyo caso se devuelve la representación binaria en bruto del resumen del mensaje.

Ejemplos

Ejemplo #1 Usandohash_file()

<?php
/* Creamos un fichero para calcular su resultante valor cifrado */
file_put_contents('example.txt','The quick brown fox jumped over the lazy dog.');

echo
hash_file('md5','example.txt');
?>

El resultado del ejemplo sería:

5c6ffbdd40d9556b73a21e63c3e0e904

Ver también

  • hash()- Generar un valor hash (resumen de mensaje)
  • hash_hmac_file()- Genera un valor cifrado mediante una clave especificada usando el método HMAC y el contenido de un fichero dado
  • hash_update_file()- Inyecta datos en un contexto de cifrado activo desde un fichero
  • md5_file()- Calcula el resumen criptográfico md5 de un archivo dado
  • sha1_file()- Calcula el hash sha1 de un archivo



hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_finalFinaliza un contexto incremental y devuelve el resultado cifrado

Descripción

hash_final(resource$context,bool$raw_output= false):string

Parámetros

context

Contexto para cifrado que se obtiene mediantehash_init().

raw_output

Cuando se establece entruela salida serán datos binarios sin formato,falsela salida serán dígitos hexadecimales en minúsculas.

Valores devueltos

Devuelve un string que contiene el mensaje cifrado como dígitos hexadecimales en minúsculas, a menos queraw_outputsea establecido en true, en cuyo caso la salida devuelta será el mensaje cifrado como datos binarios sin formato.

Ejemplos

Ejemplo #1 Ejemplo dehash_final()

<?php
$ctx
=hash_init('sha1');
hash_update($ctx,'The quick brown fox jumped over the lazy dog.');
echo
hash_final($ctx);
?>

El resultado del ejemplo sería:

c0854fb9fb03c41cce3802cb0d220529e6eef94e

Ver también

  • hash_init()- Iniciar un contexto de hashing incremental
  • hash_update()- Pega más datos en un contexto incremental de cifrado activo
  • hash_update_stream()- Pega datos en un contexto de cifrado activo desde un flujo de datos abierto
  • hash_update_file()- Inyecta datos en un contexto de cifrado activo desde un fichero



hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdfGenerate a HKDF key derivation of a supplied key input

Descripción

hash_hkdf(
    string$algo,
    string$key,
    int$length= 0,
    string$info= "",
    string$salt= ""
):string

Parámetros

algo

Name of selected hashing algorithm (i.e. "sha256", "sha512", "haval160,4", etc..) Seehash_algos()for a list of supported algorithms.

Nota:

Non-cryptographic hash functions are not allowed.

key

Input keying material (raw binary). Cannot be empty.

length

Desired output length in bytes. Cannot be greater than 255 times the chosen hash function size.

Iflengthis0, the output length will default to the chosen hash function size.

info

Application/context-specific info string.

salt

Salt to use during derivation.

While optional, adding random salt significantly improves the strength of HKDF.

Valores devueltos

Returns a string containing a raw binary representation of the derived key (also known as output keying material - OKM).

Errores/Excepciones

Throws aValueErrorexception ifkeyis empty,algois unknown/non-cryptographic,lengthis less than0or too large (greater than 255 times the size of the hash function).

Historial de cambios

VersiónDescripción
8.0.0Now throws aValueErrorexception on error. Previously,falsewas returned and anE_WARNINGmessage was emitted.

Ejemplos

Ejemplo #1hash_hkdf()example

<?php
// Generate a random key, and salt to strengthen it during derivation.
$inputKey=random_bytes(32);
$salt=random_bytes(16);

// Derive a pair of separate keys, using the same input created above.
$encryptionKey=hash_hkdf('sha256',$inputKey,32,'aes-256-encryption',$salt);
$authenticationKey=hash_hkdf('sha256',$inputKey,32,'sha-256-authentication',$salt);

var_dump($encryptionKey!==$authenticationKey);// bool(true)
?>

The above example produces a pair of separate keys, suitable for creation of an encrypt-then-HMAC construct, using AES-256 and SHA-256 for encryption and authentication respectively.

Ver también



hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algosReturn a list of registered hashing algorithms suitable for hash_hmac

Descripción

hash_hmac_algos():array

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returns a numerically indexed array containing the list of supported hashing algorithms suitable forhash_hmac().

Ejemplos

Ejemplo #1hash_hmac_algos()example

<?php
print_r
(hash_hmac_algos());

El resultado del ejemplo sería algo similar a:

Array
(
    [0] => md2
    [1] => md4
    [2] => md5
    [3] => sha1
    [4] => sha224
    [5] => sha256
    [6] => sha384
    [7] => sha512/224
    [8] => sha512/256
    [9] => sha512
    [10] => sha3-224
    [11] => sha3-256
    [12] => sha3-384
    [13] => sha3-512
    [14] => ripemd128
    [15] => ripemd160
    [16] => ripemd256
    [17] => ripemd320
    [18] => whirlpool
    [19] => tiger128,3
    [20] => tiger160,3
    [21] => tiger192,3
    [22] => tiger128,4
    [23] => tiger160,4
    [24] => tiger192,4
    [25] => snefru
    [26] => snefru256
    [27] => gost
    [28] => gost-crypto
    [29] => haval128,3
    [30] => haval160,3
    [31] => haval192,3
    [32] => haval224,3
    [33] => haval256,3
    [34] => haval128,4
    [35] => haval160,4
    [36] => haval192,4
    [37] => haval224,4
    [38] => haval256,4
    [39] => haval128,5
    [40] => haval160,5
    [41] => haval192,5
    [42] => haval224,5
    [43] => haval256,5
)

Notas

Nota:

Before PHP 7.2.0 the only means to get a list of supported hash algorithms has been to callhash_algos()which also returns hash algorithms that are not suitable forhash_hmac().

Ver también

  • hash_hmac()- Genera un valor cifrado mediante una clave especificada usando el método HMAC
  • hash_algos()- Devuelve una lista con los algoritmos de cifrado soportados


hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_fileGenera un valor cifrado mediante una clave especificada usando el método HMAC y el contenido de un fichero dado

Descripción

hash_hmac_file(
    string$algo,
    string$filename,
    string$key,
    bool$raw_output= false
):string

Parámetros

algo

Nombre del algoritmo para cifrar seleccionado (es decir "md5", "sha256", "haval160,4", etc..). Verhash_algos()para saber la lista de algoritmos soportados.

filename

URL que describe la localización del fichero cuyo contenido vamos a cifrar; Soporta fopen wrappers.

key

Clave secreta compartida que se usará para generar el mensaje cifrado de la variante HMAC.

raw_output

Cuando se establece entruela salida serán datos binarios sin formato,falsela salida serán dígitos hexadecimales en minúsculas.

Valores devueltos

Devuelve un string que contiene el mensaje cifrado como dígitos hexadecimales en minúsculas, a menos queraw_outputsea establecido en true, en cuyo caso la salida devuelta será el mensaje cifrado como datos binarios sin formato.

Ejemplos

Ejemplo #1Ejemplo de hash_hmac_file()

<?php
/* Creamos un fichero para calcular su resultante valor cifrado */
file_put_contents('example.txt','The quick brown fox jumped over the lazy dog.');

echo
hash_hmac_file('md5','example.txt','secret');
?>

El resultado del ejemplo sería:

7eb2b5c37443418fc77c136dd20e859c

Ver también

  • hash_algos()- Devuelve una lista con los algoritmos de cifrado soportados
  • hash_hmac()- Genera un valor cifrado mediante una clave especificada usando el método HMAC
  • hash_file()- Generar un valor hash usando el contenido de un fichero dado



hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmacGenera un valor cifrado mediante una clave especificada usando el método HMAC

Descripción

hash_hmac(
    string$algo,
    string$data,
    string$key,
    bool$raw_output= false
):string

Parámetros

algo

Nombre del algoritmo para cifrar seleccionado (es decir "md5", "sha256", "haval160,4", etc..). Verhash_algos()para saber la lista de algoritmos soportados.

data

Mensaje para cifrar.

key

Clave secreta compartida que se usará para generar el mensaje cifrado de la variante HMAC.

raw_output

Cuando se establece entruela salida serán datos binarios sin formato,falsela salida serán dígitos hexadecimales en minúsculas.

Valores devueltos

Devuelve un string que contiene el mensaje cifrado como dígitos hexadecimales en minúsculas, a menos queraw_outputsea establecido en true, en cuyo caso la salida devuelta será el mensaje cifrado como datos binarios sin formato. Devuelvefalsecuandoalgoes desconocido.

Ejemplos

Ejemplo #1hash_hmac()example

<?php
echohash_hmac('ripemd160','The quick brown fox jumped over the lazy dog.','secret');
?>

El resultado del ejemplo sería:

b8e7ae12510bdfb1812e463a7f086122cf37e4f7

Ver también

  • hash()- Generar un valor hash (resumen de mensaje)
  • hash_algos()- Devuelve una lista con los algoritmos de cifrado soportados
  • hash_init()- Iniciar un contexto de hashing incremental
  • hash_hmac_file()- Genera un valor cifrado mediante una clave especificada usando el método HMAC y el contenido de un fichero dado



hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_initIniciar un contexto de hashing incremental

Descripción

hash_init(string$algo,int$options= 0,string$key=null):HashContext

Parámetros

algo

Nombre del algoritmo hash seleccionado (es decir "md5", "sha256", "haval160,4", etc..). Para una lista de los algoritmos admitidos véasehash_algos().

options

Configuración opcional para la generación del cifrado, normalmente soporta solo una opción:HASH_HMAC, en el caso de utilizar esta opción tambiéndeberemosespecificar el parámetrokey.

key

Cuando se especifiqueHASH_HMACenoptions, se debe suministrar una clave secreta compartida en este parámetro para ser utilizada en el método de cifrado HMAC.

Valores devueltos

Devuelve un recurso de contexto para cifrado, el cual será incrementado conhash_update(),hash_update_stream(),hash_update_file(), yhash_final().

Historial de cambios

VersiónDescripción
7.2.0Uso de funciones de hash no criptográficas (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) conHASH_HMACha sido deshabilitado.
7.2.0DevuelveHashContexten lugar de recurso.

Ejemplos

Ejemplo #1 Ejemplo de hashing incremental

<?php
$ctx
=hash_init('md5');
hash_update($ctx,'The quick brown fox ');
hash_update($ctx,'jumped over the lazy dog.');
echo
hash_final($ctx);
?>

El resultado del ejemplo sería:

5c6ffbdd40d9556b73a21e63c3e0e904

Ver también

  • hash()- Generar un valor hash (resumen de mensaje)
  • hash_algos()- Devuelve una lista con los algoritmos de cifrado soportados
  • hash_file()- Generar un valor hash usando el contenido de un fichero dado
  • hash_hmac()- Genera un valor cifrado mediante una clave especificada usando el método HMAC
  • hash_hmac_file()- Genera un valor cifrado mediante una clave especificada usando el método HMAC y el contenido de un fichero dado



hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2Genera una derivación de clave PBKDF2 de una contraseña proporcionada

Descripción

hash_pbkdf2(
    string$algo,
    string$password,
    string$salt,
    int$iterations,
    int$length= 0,
    bool$raw_output= false
):string

Parámetros

algo

El nombre del algoritmo hash seleccionado (esto es,"md5","sha256","haval160,4", etc.). Véasehash_algos()para una lista de los algoritmos admitidos.

password

La contraseña a usar para la derivación.

salt

La sal a usar para la derivación. Este valor debería ser generado aleatoriamente.

iterations

El número de iteraciones internas para realizar la derivación.

length

La longitud del string de salida. Siraw_outputestrue, se corresponde con la longitud en bytes de la clave derivada; siraw_outputesfalse, se corresponde con dos veces la longitud en bytes de la clave derivada (ya que cada byte de la clave es devuelto como dos dígitos hexadecimales).

Si se pasa0, se usará la salida completa del algoritmo proporcionado.

raw_output

Cuando se establece atrue, genera datos binarios puros.falsegenera dígitos hexadecimales en minúsculas.

Valores devueltos

Devuelve un string que contiene la clave derivada como dígitos hexadecimales en minúsculas, a menos queraw_outputsea establecido atrue, en cuyo caso devuelve la represetación binaria pura de la clave derivada.

Errores/Excepciones

Se emitirá unE_WARNINGsi el algoritmo es desconocido, el parámetroiterationses menor o igual a0, el parámetrolengthes menor que0o el parámetrosaltes demasiado grande (mayor queINT_MAX- 4).

Ejemplos

Ejemplo #1 Ejemplo de uso básico dehash_pbkdf2()

<?php
$contraseña
="password";
$iteraciones=1000;

// Generar una IV aleatoria usando mcrypt_create_iv(),
// openssl_random_pseudo_bytes() u otra fuente disponible de aleatoriedad
$sal=mcrypt_create_iv(16,MCRYPT_DEV_URANDOM);

$hash=hash_pbkdf2("sha256",$contraseña,$sal,$iteraciones,20);
echo
$hash;
?>

El resultado del ejemplo sería algo similar a:

120fb6cffcf8b32c43e7

Notas

Precaución

El método PBKDF2 se puede usar para el almacenamiento de contraseñas de hash. Sin embargo, se debería observar quepassword_hash()ocrypt()conCRYPT_BLOWFISHson más adecuados para el almacenamiento de contraseñas.

Ver también

  • crypt()- Hash de cadenas de un sólo sentido
  • password_hash()- Crea un hash de contraseña
  • hash()- Generar un valor hash (resumen de mensaje)
  • hash_algos()- Devuelve una lista con los algoritmos de cifrado soportados
  • hash_init()- Iniciar un contexto de hashing incremental
  • hash_hmac()- Genera un valor cifrado mediante una clave especificada usando el método HMAC
  • hash_hmac_file()- Genera un valor cifrado mediante una clave especificada usando el método HMAC y el contenido de un fichero dado



hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_fileInyecta datos en un contexto de cifrado activo desde un fichero

Descripción

hash_update_file(resource$hcontext,string$filename,resource$scontext=null):bool

Parámetros

hcontext

Un contexto de cifrado devuelto porhash_init().

filename

URL que describe la ubicación del fichero a cifrar; admite envolturas fopen.

scontext

Un contexto de flujo, como el devuelto porstream_context_create().

Valores devueltos

Devuelvetrueen caso de éxito ofalseen caso de error.

Ver también

  • hash_init()- Iniciar un contexto de hashing incremental
  • hash_update()- Pega más datos en un contexto incremental de cifrado activo
  • hash_update_stream()- Pega datos en un contexto de cifrado activo desde un flujo de datos abierto
  • hash_final()- Finaliza un contexto incremental y devuelve el resultado cifrado
  • hash()- Generar un valor hash (resumen de mensaje)
  • hash_file()- Generar un valor hash usando el contenido de un fichero dado